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Preface 



this book contains technical information pertaining to the IBM Oper- 
ating System/2™ (0S/2™1). 

This book covers topics for the system programmer, and application 
developer. The reader should be knowledgeable about operating 
systi^ms and be proficient in one or more of the IBM Personal Com- 
puter programming languages. It is also assumed that you are 
familiar with the 80286 architecture. 

This book contains six chapters that describe the OS/2 Application 
Programming Interface (API) Function Requests. The function 
requests are arranged In alphabetical order and reflect each call's 
purpose, calling sequence, parameter definitions, return codes, con- 
siderations and remarks. 

Note: For a complete error code list refer to the Appendix at the back 
of this book. 
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1 IBM Operating System/2™ and OS/2 are trademarks of 
International Business Machines Corporation 
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Chapter 1. IBM Operating System/2^'^ 
Function Requests 



Applications built under IBM Operating System/2(OS/2) use a 
dynannic link nneclianism (far CALL) to access all services. The call 
interface Implementation is outlined below: 

The OS/2 function requests must operate 

1. for all memory models 

2. for a wide range of IBM supported languages 

3. for all dynamic link entries. 

The stack passes call parameters when OS/2 service is requested, 
using a call-return interface. Before a call is issued, parameters are 
pushed onto the stack. The parameters are copied by the hardware, 
from the requestor's stack to the receiving program's stack. All OS/2 
functions are invoked using the call-return interface. The following 
section explains how to use the call interface system. 



How OS/2 Function Requests Woric 

A function call is declared EXTERNAL FAR when It is coded to a 
dynamically linked subroutine. The compiler generates a standard 
external reference. Library names that contain the dynamic link defi- 
nition records are sent to the linker when the object module links. 
These records provide a correspondence between the called entry 
point and the module file that contains the routine being called. 



OS/2 Function Request Format 

The Function Request interfaces are set up in this book descriptively 
rather than in coding sequence example. The conventions described 
below are employed throughout this document. 

Since all parameters are pushed onto the stack, there are several 
pseudo-instructions that describe these operations. 
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Operandi Description 



PUSH pushes various size items onto tlie stacl<. The data 

types are described below. 

PUSH@ pushes the address of an item onto the stack. All 

addresses in these interfaces are composed of a 32-bit 
value, a 16-bit selector, and a 16-bit offset. These 
addresses point to data item types. 

CALL calls a function and accesses it via F>A/? C^LLS. A 

parameter list contains several data items. 

WORD (2 bytes) is passed by value (pushed onto the stack) or 
by reference (the address is passed on the stack). 

DWORD (4 bytes) Is passed by value or by reference. 

ASCiiZ Is a null ( OOH ) terminated character string, accessed 
by reference. 

OTHER pushes the address of a structure on to the stack and is 
accessed by reference. 

Note: The OS/2 function calls in this book are described in mixed 
case for readability. The function call names are known to the 
system as upper case character strings. For example, the OS/2 func- 
tion call "DosQetlnfoSeg" is actually the external name 
"DOSGETINFOSEG" 

If you are using a compiler which will generate mixed case external 
names, you may wish to code the OS/2 function calls In upper case. 
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Chapters OS/2 DOS Calls 



This chapter reflects the DOS Application Program Interface (API) 
only. For a complete list of ail return codes, refer to the Appendix in 
the back of this book. 

For information regarding other functional characteristics of the API, 
refer to the OS/2 Technical Reference, Volume 1. 
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DosAllocHuge - 
Allocate Huge Memory 



Purpose 

DosAllocHuge allocates multiple segments of memory. 
Calling Sequence 

EXTRN DosAllocHuge: FAR 

PUSH WORD NumSeg 

PUSH WORD Size 

PUSH? WORD Selector 

PUSH WORD MaxNumSeg 

PUSH WORD Flags 

CALL DosAllocHuge 

Where 

NumSeg 

Is the number of 65536-byte segments requested. 
Size 

Is the number of bytes requested In the last non-65536-byte 
segment. A value of zero Indicates none. 

Selector 

is where the selector of the first segment allocated is returned. 
MaxNumSeg 

is the maximum number of 65536-byte segments an object occu- 
pies as a result of any subsequent DosRealiocHuge, (see 
"DosReallocHuge - Change Huge Memory Size" on 
page 2-198). If MaxNumSeg is 0, OS/2 assumes this segment will 
never be increased by DosReallocHuge beyond its original size, 
though it may be decreased. 

Flags 

indicate sharing attributes of the allocated segment. The fol- 
lowing bit values are defined below: 

Bit 0 (0001b) = 

segment Is shareable through DosGiveSeg 
Bit 1 (0010b) = 

segment is shareable through DosGetSeg 



; Number of 65536-byte segments 
; Number of bytes in last segment 
; Selector allocated (returned) 
;Max number of 65536-byte segments 
;Anocation flags 
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DosAllocHuge - 
Allocate Huge Memory 



Bit 2 (0100b) = 

segment is discardable in low memory situations. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Family API Considerations 

Some options operate differently in the DOS mode than they do In the 
OS/2 mode. Therefore, the following considerations apply to 
DosAllocHuge when coding in the DOS mode: 

• Requested Size value Is rounded up to the next paragraph. 

• Selector Is the actual segment address allocated. 

• Flags must be set equal to zero. 

• MaxNumSeg is ignored. 

Remarks 

The memory allocated by DosAllocHuge Is movable and swappable. 
Increment the selector of the first segment to obtain a selector for a 
second segment. Use the increment added to the second selector to 
address the third segment, and so forth. Derive the increment by 
shifting the value "1 " to the left by the amount returned as a shift 
count by DosGetHugeShlft. For example: 

• Assume DosAllocHuge is issued with NumSeg equal to three. 
The first segment allocated is at selector number 63. 

• If DosGetHugeShift returns a shift count of four, shifting the value 
one by this amount results In an Increment of 16 

• Adding this increment to selector number 63 results in selector 79 
as the second selector. Adding the Increment to 79 yields 
selector 95 as the third selector. 

• The three selector values (63, 79, and 95) are saved by the 
program and referenced for later use. 

For any segments allocated as discardable, the data in the segments 
is lost when they are discarded in low memory situations. To refer- 
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DosAllocHuge - 
Allocate Huge Memory 



ence the segments again the operator must reallocate them and 
recreate the data. 

For huge segments, discarding is forced on all other segments in the 
huge allocation when one segment is discarded. 

Memory allocated by DosAllocHuge is deallocated by DosFreeSeg. 
The selector returned by DosAllocHuge is passed to DosFreeSeg, 
which frees all the allocated memory. 
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DosAHocSeg - 
Allocate Segment 



Purpose 

DosAllocSeg allocates a segment of memory to a requesting process. 
Calling Sequence 

EXTRN DosAllocSeg: FAR 

PUSH WORD Size 
PUSH© WORD Selector 
PUSH WORD Flags 
CALL DosAllocSeg 

Where 

Size 

is the number of bytes requested. The value specified must be 
less than or equal to 65535. A value of zero indicates 65536 bytes. 

Selector 

Is where the selector of the allocated segment is returned. 
Flags 

indicate sharing attributes of the allocated segment. The fol- 
lowing bit values are defined below: 

Bit 0 (0001b) = 

segment is shareable through DosGiveSeg 
Bit 1 (0010b) = 

segment is shareable through DosGetSeg 
Bit 2 (0100b) = 

segment Is discardable In low memory situations. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 



; Number of bytes requested 
; Selector allocated (returned) 
;A1 location flags 
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DosAllocSeg - 
Allocate Segment 



Family API Considerations 

Some options operate differently in tlie DOS mode than they do in the 
OS/2 mode. Therefore, the following restrictions apply to 
DosAllocSeg when coding In the DOS mode: 

• Requested Size value is rounded up to the next paragraph. 

• Selector is the actual segment address allocated. 

• If Flag = one, an error is returned. 

Remarks 

The memory allocated by DosAllocSeg is movable and swappable. 
To allocate a segment of memory that can be discarded when not in 
use, use DosLockSeg and DosUnlockSeg in conjunction with 
AllocFlags bit two set. In low memory situations, a segment can be 
swapped if it is locked and if bit 2 is set. If the segment is unlocked, it 
may be discarded. 

For any segments allocated as discardable, the data in the segments 
is lost when they are discarded in low memory situations. To refer- 
ence the segments again the operator must reallocate them and 
recreate the data. 

For huge segments, discarding is forced on all other segments In the 
huge allocation when one segment is discarded. 
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DosAllocShrSeg - 
Allocate Shared Segment 



Purpose 

DosAllocShrSeg allocates a shared memory segment to a process. 
Calling Sequence 

EXTRN DosAllocShrSeg: FAR 

PUSH WORD Size 
PUSH@ ASCIIZ Name 
PUSH@ WORD Selector 
CALL DosAl 1 ocShrSeg 

Where 

Size 

is the number of bytes requested. The value specified must be 
less than or equal to 65535. A value of 0 indicates 65536 bytes. 

Name 

Is a symbolic name to be associated with the shared memory 
segment to be allocated. The name string that specifies the name 
for the shared memory segment must include the prefix 
\SHAREMEM\. For example \SHAREMEM\PUBLiC.DAT. 

Selector 

is where the selector of the allocated segment is returned. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

Memory allocated by DosAllocShrSeg can be moved and swapped. 
The selector returned to the issuing process by DosAllocShrSeg is 
the same as that returned to another process when it issues 
DosGetShrSeg to access the same segment. 



: Number of bytes requested 
;Name string 

; Selector allocated (returned) 
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DosAllocShrSeg - 
Allocate Shared Segment 



The name assigned to the segment should be used by another 
process on its DosGetShrSeg call to access the same segment. 

The maximum number of segments a process can define with 
DosAllocShrSeg or access with DosGetShrSeg is 30. 
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DosBeep ~ 
Generate Sound From Speaker 



Purpose 

DosBeep generates sound from the speaker. 
Calling Sequence 

EXTRN DosBeep: FAR 

PUSH WORD Frequency ; Hertz (Hz) 

PUSH WORD Duration ; Length of sound 
CALL DosBeep 

Where 

Frequency 

' is the tone in Hertz (cycles per second) In the range 37 to 32767. 
Duration 

is the length of the sound in milliseconds. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

DosBeep executes synchronously. An application program that 
invokes DosBeep waits until the specified number of milliseconds 
expire before It resumes execution. 
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Commit File's Cache Buffers 



Purpose 

DosBufReset flushes a requesting process's cache buffers for a spe- 
cific file handle. 

Calling Sequence 

EXTRN DosBufReset: FAR 

PUSH WORD FileHandle ;File handle 
CALL DosBufReset 

Where 

FileHandle 

is the file handle whose buffers are to be flushed. If FileHandle = 
FFFFH, all of the process's cache buffers that require file I/O are 
written out. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

Upon issuing DosBufReset, a file's directory entry is updated as if the 
file had been closed, however, the file remains in the open state. 

To flush a requesting process's cache buffers using DosBufReset 
could require the user to mount and dismount a large number of 
removable volumes. 
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Perform Case Mapping 



Purpose 

DosCaseMap performs case mapping on a string of binary values that 
represent ASCil cliaracters. 

Calling Sequence 

EXTRN DosCaseMap: FAR 

PUSH WORD Length ; Length of string to case map 

PUSH© OTHER Structure ; Input data structure 
PUSH© OTHER BinaryString ; Address of string of binary 
CALL DosCaseMap 

Where 

Length 

is the length of the string of binary values to be case mapped. 
Structure 

is a two word input data structure where: 
word 0 

Country Code (0 - default country) 
word 1 

Code Page ID (0 - current process code page). 
BinaryString 

is a string of binary characters to be case mapped. They are case 
mapped in place so the results appear in BinaryString and the 
input is destroyed. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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Perform Case Mapping 



Remarks 

The case map information is tal<en from the country information file. 
See the COUNTRY statement in the IBM Operating System/2™ User's 
Reference for information on how to specify the country information 
file. 

if the Country Code in Structure is 0, the case mapping is performed 
using the information for the country specified in the COUNTRY state- 
ment in CONFIG.SYS. If the Country Code in Structure is not zero, the 
case mapping is performed using the information for that country. 

If the CodePagelD in Structure is 0, the case mapping is performed 
using the information for the current process code page. Refer to 
"DosSetCp - Set Code Page" on page 2-222 and the CHOP 
command in the IBM Operating System/2™ User's Reference for 
information on setting the process code page. If the CodePagelD in 
Structure is not 0, the case mapping is performed using the informa- 
tion for that code page. 

The returned country dependent information may be for the default 
country and current process code page or for a specific country and 
code page. 
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DpsChDir ~ 
Change Current Directory 



Purpose 

DosChDir defines the current directory for tiie requesting process. 
Calling Sequence 

EXTRN DosChDir: FAR 

PUSH© ASCIIZ DirName ;Di rectory path name 

PUSH DWORD 0 : Reserved (must be zero) 

CALL DosChDI r 

Where 

DirName 

is tlie directory patii name. The string is limited to 64 characters. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

The directory path is not changed if any member of the path does not 
exist. The current directory changes oniy for the requesting process. 
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DosChgFilePtr - 

Change (Move) File Read/Write Pointer 



Purpose 

DosChgFilePtr moves the read/write pointer in accordance with the 
method specified. 

Calling Sequence 

EXTRN DosChgFilePtr: FAR 

PUSH WORD FileHandle 

PUSH DWORD Distance 

PUSH WORD MoveType 

PUSH@ DWORD NewPointer 

CALL DosChgFilePtr 

Where 

FileHandle 

is the handle returned by a previous DosOpen call. 
Distance 

is the distance (offset) to move in bytes. 

IVIoveType 

is the method of moving: 

If value = 0 

move pointer Distance bytes (offset) from the beginning of the 
file. 
If value = 1 

move pointer to the current location plus offset. 
If value = 2 

move pointer to the end-of-file plus offset. Use this method to 
determine a file's size. 

NewPointer 

is the area where the system returns the new pointer location. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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;File handle 

•.Distance to move in bytes 
;Method of moving (0, 1, 2) 
-.New Pointer Location 



DosChgFilePtr - 
Change (Move) File Read/Write Pointer 

Remarks 

None 
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DosCLIAccess - 
Request CLI/STI Privilege 



Purpose 

DosCLIAccess requests I/O privilege for disabling and enabling inter- 
rupts. Access to ports must be granted via DosPortAccess. 

Calling Sequence 

EXTRN DosCLIAccess: FAR 
CALL DosCLIAccess 

Where 

None 

Returns 

AX = 0 

Remarks 

Applications that only use CLI/STI in lOPL segments must request 
CLI/STI privilege from the operating system. 

Applications that use IN/OUT instructions to I/O ports must request 
I/O privilege with DosPortAccess. (See "DosPortAccess — Request 
Port Access" on page 2-164 for more detail) Request for port access 
will also grant CLI/STI privilege from the operating system. 
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Close Ml^ Handle 



Purpose 

DosClose closes a specific file handle. 
Calling Sequence 

EXTRN DosClose: FAR 

PUSH WORD F11eHand1e :F11e handle 
CALL DosClose 

Where 

FileHandle 

is the handle returned by a previous DosOpen or DosMakePipe 
call. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

Closing a file handle closes the file, updates the directory, and writes 
the file's internal buffers to the media. 

When hard error popups are disabled, issue DosBufReset before 
issuing DosClose. 
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Close Queue 



Purpose 

DosCloseQueue closes the queue in use by the requesting process. 
Calling Sequence 

EXTRN DosCloseQueue: FAR 

PUSH WORD QueueHandle ; Handle of queue 
CALL DosCloseQueue 

Where 

QueueHandle 

Is the handle returned from a previous DosCreateQueue or 
DosOpenQueue call. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

When DosCloseQueue is issued, If the requesting process Is the 
owner of the queue, all outstanding elements are purged. Other proc- 
esses that have the queue open receive the QUEUE_DOES 
NOT_EXIST (Invalid queue handle) return code on the next request. 

For a writer of the queue using DosCloseQueue, access to the queue 
Is terminated, but the queue Is not affected. 
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Close System Semaphore 



Purpose 

DosCloseSem closes a specific system semaphore. 
Calling Sequence 

EXTRN DosCloseSem: FAR 

PUSH DWORD SemHandle ; Semaphore handle 
CALL DosCloseSem 

Where 

SemHandle 

is the handle returned from a previous DosCreateSem or 
DosOpenSem call. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

When all processes using the semaphore issue DosCloseSem, the 
semaphore is deleted. If a process terminates with open 
semaphores, the system closes the semaphores. If any of the 
semaphores are owned by the current process, the first thread given 
the semaphore wakes with the ERROR_ SEM_OWNER_DIED. This 
indicates the owner of the semaphore ended without releasing it and 
the resources are in an indeterminate state. 
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DosCreateCSAIias - 
Create CS Alias 



Purpose 

DosCreateCSAIias creates a code segment alias descriptor for a data 
segment passed as Input. 

Calling Sequence 

EXTRN DosCreateCSAl i as : FAR 

PUSH WORD DataSelector ;Data segment selector 

PUSH@ WORD CodeSelector ;Code segment selector (returned) 

CALL DosCreateCSAIias 

Where 

DataSe/ecfor 

is tlie data segment selector. 

CocfeSe/ecfor 

is wiiere the selector of the code segment alias descriptor is 
returned. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Family API Considerations 

The returned selector is the segment address of the allocated 
memory. When the returned selector or the original selector is 
freed, OS/2 immediately deallocates the block of memory. 

Remarks 

Any selector valid for DS, ES or SS, can be used as the data segment 
selector passed as input to DosCreateCSAIias. However, its segment 
must be exclusively accessible by the process and not a huge 
segment. Shared memory segments and dynamically linked global 
data segments cannot be used as input for DosCreateCSAIias. 
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Create CS Alias 



The code segment selector returned as output is valid for CS. If a 
valid procedure Is stored In the segment that uses the data selector, 
the procedure can be called using the CS alias. The procedure is 
called from privilege level three or I/O privilege level. 

Use DosFreeSeg to free a CS alias created with DosCreateCSAIias. 
Procedures in the segment continue to be referenced if the data 
selector for the aliased segment is passed to DosFreeSeg, however 
the CS alias selector is not affected. 



2-21 
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Create Queue 



Purpose 

DosCreateQueue creates a queue owned by a creating process. 
Calling Sequence 

EXTRN DosCreateQueue : FAR 

PUSH@ WORD RWHandle 

PUSH WORD QueuePrty 

PUSH@ ASCIIZ QueueName 

CALL DosCreateQueue 

Where 

RWHandle 

is wliere tlie read/write liandle of the queue is returned. The 
handle is used by the requestor on return. 

QueuePrty 

indicates the priority ordering algorithm to use for eieinents 
placed in the queue. The Valid values and their meanings are: 

0 = FIFO queue 

1 = UFO queue 

2 = Priority queue (sender specifies priority zero to 15.) 
QueueName 

Is the name of the queue. The name string that specifies the 
name for the queue must include \QUEUES\ as a path name. For 
example, \QUEUES\RETRIEVE\CONTROL.QUE is a valid queue 
name. The same name must be specified when calling 
DosOpenQueue for the process which adds elements to the 
queue. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 



; Queue handle (returned) 

; Ordering to use for elements 

;Queue name string 
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Create Queue 



Remarks 

A queue must be created before it can be opened. The process that 
creates a queue owns the queue. When specifying a name for a 
queue, the ASCII! name string must include the prefix \QUEUES\. 
Only the owner can access or remove the elements in a queue. Any 
process can open a queue and place data in it. When a queue is 
created, each process writing to it must open the queue through 
DosOpenQueue. When a process creates or opens a queue, any 
thread in that process can access the queue with equal authority. 
This provides the capability for multi-server queues. 

A queue exists when it is created and ceases to exist when the owner 
closes it. if other processes have a queue open when the owner 
closes it, subsequent requests return with the "queue does not exist" 
return code. 
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Create System Semaphore 



Purpose 

DosCreateSem creates a system semaphore used by semaphore 
manipulation calls such as DosSem Request, DosSemClear, 
DosSemSet, DosSemSetWait, DosSem Wait, and DosMuxSemWait. 

Calling Sequence 

EXTRN DosCreateSem: FAR 

PUSH WORD NoExclusive ;Indicate no exclusive ownership 

PUSM@ DWORD SemHandle ; Semaphore handle (returned) 

PUSH@ ASCIIZ SemName ; Semaphore name string 

CALL DosCreateSem 

Where 

NoExclusive 

is an indicator that the owning process does not want exclusive 
ownership of the semaphore. Other processes can alter the state 
of the semaphore while it is owned. 

If value = 0 

the owning process has exclusive ownership of the 
semaphore. 
If value = 1 

exclusive ownership is not required. 

SemHandle 

is where the handle assigned the semaphore Is returned. 
SemName 

is the name of the system semaphore. The name string that speci- 
fies the name for the semaphore must include \SEM\ as a path 
name. For example, \SEM\RETRIEVE\SIGNAL.SEM is a valid 
semaphore name. The same name must be specified when calling 
DosOpenSem for any other process that needs to access the same 
semaphore. 
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Create System Semaphore 



Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

DosCreateSem creates a system semaphore to control access to a 
serially reusable resource through multiple asynchronous threads. 
DosCreateSem opens and allows access to a semaphore. The 
NoExclusive operand allows an owned semaphore to be modified by 
a process other than the owner. When the system semaphore is 
exclusive this means the semaphore has a use count associated with 
It. When specifying the name for a system semaphore, the ASCIIZ 
name string must include the prefix \5EM\. 
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Create Another Thread of Execution 



Purpose 

DosCreateThread creates an asynchronous thread of execution under 
the current process. 

Calling Sequence 

EXTRN DosCreateThread : FAR 

PUSH DWORD PgmAddress ; Program address 

PUSH© WORD ThreadlDWord ;New thread ID (returned) 

PUSH DWORD NewThreadStack ;End of stack 

; for new thread 

CALL DosCreateThread 

Where 
PgmAddress 

is the program to receive control under the new thread. 
ThreadlDWord 

is where the thread ID of the new thread is to be returned. 

NewThreadStack 

points to the end of the new thread's stack. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

DosCreateThread causes a far call to be generated by the systenn at 
PgmAddress. The new thread is identical to the requesting thread 
and can access ail files and resources owned by the parent process. 
Operations of all threads within a process are identical. The only 
thread-specific information maintained is register contents, stacl<, and 
dispatching priority. 
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Create Another Thread of Execution 

Within a given process, any thread can open a file or device and any 
other thread can subsequently Issue read or writes to that handle. A 
similar case exists with pipes, queues and system semaphores. 
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Wait for Child Termination 



Purpose 

DosCwait places the current thread in a wait state until a child 
process terminates. When this occurs, the process 10 and termination 
code of the ending process is returned. 



Calling Sequence 

EXTRN DosCwait -.FAR 



PUSH WORD 

PUSH WORD 

PUSH@ DWORD 

PUSH@ WORD 

PUSH WORD 

CALL DosCwait 



ActionCode ; Execution options 

WaitOption ;Wait options 

ReturnCodes ;Termi nation Codes (returned) 

ProcessIDWord ; Process ID (returned) 

ProcessID ; Process ID of process to wait for 



Where 

ActionCode 

indicates the process of interest: 

If value = 0 

the current thread waits until the indicated process ends. 
If value = 1 

the current thread waits until the indicated process and all its 
child processes end. 

WaitOption 

indicates return if no child process ends: 

If value = 0 

the current thread waits if no child process ends or until there 
are no child processes outstanding. 
If value = 1 

the current thread does not wait for child processes to end. 
ReturnCodes 

is where the termination code and result code indicate the reason 
for the child's termination is returned. 
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Wait for Child Termination 



The first word is a termination code. It is furnislied by the system, 
and describes why the child terminated. The values returned and 
their meanings are: 

0 = EXIT (normal exit) 

1 = hard error abnormally end (or stop) execution 

2 = trap operation 

3 = unintercepted DosKillProcess. 

The second word passes the ResultCode specified by the termi- 
nating process on Its last DosExit call. 

ProcesslDWord 

is where the process ID of the ending process is returned. 

ProcessID 

is the ID of the terminating process being waited for: 
If value = 0 

the current thread waits until any child process ends. 
If value # 0 

the current thread waits until the indicated process and all its 
child processes end. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

DosCwait waits for completion of a child process. If a child process 
starts other processes, DosCwait waits for the grandchild processes 
to complete before it returns, it does not report their status. If the 
indicated child process has multiple threads, the result code is 
returned on the last DosExit request. 

If no child processes were started, DosCwait returns with an error. If 
no child processes terminate, DosCwait waits until one terminates 
before returning to the parent. 

Checl< the process ID to verify which child a return code is from. To 
wait for all child processes and grandchild processes to end, issue 
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Wait for Child Termination 



DosCwait (with ActionCode = 1, ProcessID = 0) repeatedly until the 
NO_CH|LD_PROCESS_EXiSTS return code is given. 

If DosCwait is used to wait for a child process to end, use 
DosExecPgm to create the child process and indicate 
" Asy ncTraceFI ags=2 " . 
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Delete File 



Purpose 

DosDelete removes a directory entry associated witli a filename. 
Calling Sequence 

EXTRN DosDelete: FAR 

PUSH© ASCIIZ FileName ; Filename path 

PUSH DWORD 0 : Reserved (must be zero) 

CALL DosDel ete 

Where 

FileName 

is the name of the file to be deleted. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

Global filename characters are not allowed in any part of the ASCIIZ 
string. DosDelete cannot delete read-only files. To delete a 
read-only file, use DosSetFlleMode to change the file's read-only 
attribute to 0, then delete the file. 
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Get Device Configuration 



Purpose 

DosDevConfig gets information about attaclied devices. 
Calling Sequence 

EXTRN DosDevConfig: FAR 

PUSH@ OTHER Devicelnfo ; Returned information 

PUSH WORD Item ;Item number 

PUSH WORD Parm ; Reserved 
CALL DosDevConfig 

Where 

Devicelnfo 

Is where the requested information is returned. 
Item 

indicates what device information to return: 



Item 


Returned Device Information 


0 


Number of printers attached 


1 


Number of RS232 ports 


2 


Number of internal dislcette drives 


3 


Presence of math coprocessor (where 0 = not present, 1 




= present) 


4 


PC Submodel Type ( where the return is the system sub- 




model byte) 


5 


PC Model Type ( where the return is the system model 




byte) 


6 


Display adapter type (where 0 = monochrome mode com- 




patible, 1 = other). 



Parm 

is reserved and should be set to 0. 
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Get Device Configuration 



Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

The system model (function 5) and submodel (function 4) Information 
is obtained from BIOS. 

In addition, the number of devices attached in a PS/2 environment 
reflect only devices that are "awake". Devices that are "asleep" are 
not counted. 
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I/O Control for Devices 



Purpose 

DosDevlOCtI performs control functions on a device specified by an 
opened device handle. 



Calling Sequence 

EXTRN DosDevlOCtI: FAR 

PUSH@ OTHER Data 

PUSH? OTHER ParmList 

PUSH WORD Function 

PUSH WORD Categorj^ 

PUSH WORD DevHandle 

CALL DosDevlOCtI 



;Data area 

; Command arguments 

; Device function 

; Device category 

; Specifies the device 



Where 

Data 

is tlie data area. 

ParmList 

is a command-specific argument list. 
Function 

Is the device-specific function code. 

Category 

is the device category. 

DevHandle 

is a device handle returned by DosOpen or a standard (open) 
device handle. 



Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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I/O Control for Devices 



Family API Considerations 

Level of support for DosDevlOCtI is Identified by category and func- 
tion call, with a noted restriction if it is not supported by DOS 3.3. 
Functions tend to be more restrictive in lower versions of DOS. 

• Category 1 supported In Family API 

• 41 h Set Baud Rate 

• 42h Set Line Control 

• All other Category one functions not supported for DOS 3.3 

• Category 2 not supported in the Family API 

• Category 3 not supported in the Family API 

• Category 4 not supported in the Family API 

• Category 5 supported in the Family API 

• 42h Set Frame Control (for IBM Graphics Printers only) 

• 44h Get Infinite Retry (DOS 3.3 the function is in effect for duration 
of program only.) 

• 46h Initialize Printer 

• 62h Get Frame Control (not supported for DOS 3.3) 

• 64h Get Infinite Retry 

• 66h Get Printer Status 

• Category 6 not supported by the Family API 

• Category 7 not supported by the Family API 

• Category 8 supported in Family API 

• OOh Lock Drive (not supported below DOS 3.3) 

• 01 h Unlock Drive (not supported below DOS 3.3) 

• 02h Redetermine Media (not supported below DOS 3.3) 

• 03h Set Logical Map (not supported below DOS 3.3) 

• 20h Block Removable (not supported below DOS 3.3) 

• 21 h Get Logical Map (not supported below DOS 3.3) 

• 43h Set Device Parameters (not supported DOS 3.3) 

• 44h Write Track (not supported DOS 3.3) 

• 45h Format Track (not supported DOS 3.3) 

• 63h Get Device Parameters (not supported DOS 3.3) 

• 64h Read Track (not supported DOS 3.3) 

• 65h Verify Track (not supported DOS 3.3) 

• Category 9 reserved 

• Category 10 (OAh) not supported in the Family API 

• Category 11 (OBh) not supported in the Family API. 
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I/O Control for Devices 



Remarks 

Values returned in the range hex FFOO to FFFF are user dependent 
error codes. Values returned in the range hex FEOO to FEFF are 
device driver dependent error codes. Refer to the IBM Operating 
System/2 Technical Reference, Volume 1 for complete listing of 
DevHIp calls. 
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Duplicate File Handle 



Purpose 

DosDupHandle returns a new file handle for an open file that refers to 
the same file at the same position. 

Calling Sequence 

EXTRN DosDupHandle: FAR 

PUSH WORD OldFileHandle ; Existing file handle 

PUSH@ WORD NewFileHandle ;New file handle (returned) 

CALL DosDupHandle 

Where 

OldFileHandle 

is the current file handle. 

NewFileHandle 

is where the new file handle is returned. When DosDupHandle is 
called, if this word contains FFFFH, OS/2 allocates a new file 
handle and returns its value here. If this word contains any other 
value, OS/2 assumes this value is to be the new file handle. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

Duplicating the handle duplicates and ties all handle-specific informa- 
tion between OldFileHandle and NewFileHandle. 

A file handle value other than FFFFH specified in NewFileHandle 
causes OS/2 to close the file handle before redefining it as the dupli- 
cate of OldFileHandle. 
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Duplicate File Handle 



The values for NewFileHandle include: 



FFFFH 
OOOOH 
0001 H 
0002H 



= standard Input 
= standard output 
= standard error 



= assign new handle 



nnnn 



the handle of any currently open file. 



Note: Avoid using other arbitrary values. 

If the read/write pointer of either handle is moved by DosRead, 
DosWrite, or DosChgFilePtr, the pointer for all duplicated handles is 
also changed. 

Issuing DosClose against a file handle does not affect the duplicate 
handle. 
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Enter Critical Section of Execution 



Purpose 

DosEnterCritSec disables tliread switcliing for tlie current process. 
Calling Sequence 

EXTRN DosEnterCritSec: FAR 
CALL DosEnterCritSec 

Where 

None 

Returns 

iF AX = 0 tlien NO error 
ELSE AX = error code 

Remarks 

Wlien tlie current tliread issues DosExitCritSec, otiier tlireads in a 
process resume normal dispatching. 

If a signal occurs, the first thread begins execution to process the 
signal even though another thread in the process has a 
DosEnterCritSec active. Any processing the first thread does to 
satisfy the signal must not access the critical resource intended to be 
protected by the DosEnterCritSec. 

A count of the number of outstanding DosEnterCritSec requests is 
maintained. The count Is increase on DosEnterCritSec requests and 
decreased on DosExitCritSec requests. A DosExitCritSec request 
does not cause normal thread dispatching to restore while the count 
is greater than zero. This count is maintained in a word and if over- 
flow is encountered, the count is set to the maximum value, an error 
is returned, and the operation does not perform. 
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Enter Critical Section of Execution 

Once a DosEnterCritSec request has been made, no dynamic linl< 
calls should be made until the corresponding DosExitCritSec call has 
been completed. 
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Classify Error Codes 



Purpose 

DosErrClass helps OS/2 applications respond to error codes (return 
codes) received from the OS/2 API. 

Calling Sequence 

EXTRN DosErrClass: FAR 

PUSH WORD Code 

PUSH@ WORD Class 

PUSH@ WORD Action 

PUSH@ WORD Locus 

CALL DosErrCI ass 

Where 
Code 

Is the error code returned by an OS/2 function. 
Class 

Is where the classification of that error is returned. 
4ct/on 

is where the recommended action for that error is returned. 
Locus 

Is where the origin of the error is returned. 
Returns 

AX = 0 

Remarks 

The input is the return code returned from another function call, and 
the output is a classification of the return and recommended action. 
Depending on the application, the recommended action could be fol- 
lowed, or a more specific application recovery could be performed. 

When DosErrClass is called by a family application, it returns a valid 
error classification for returns that have occurred. The classifications 



; Error code for analysis 
;Error classification (returned) 
; Recommended action (returned) 
; Error locus (returned) 
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of a given return code may not be the same for the Family API and 
the OS/2 mode applications. 

The following values are returned in Class, Action, and Locus: 
Class Definitions 



Value 


l\/lnemonlc 


Description 


1 


OUTRES 


Out of resources 


2 


TEMPSIT 


Temporary situation 




Al ITU 

Mu 1 n 


Muinorizaiion laiieu 


4 


INTRN 


Internal error 


5 


HRDFAIL 


uevice naruware laiiure 


6 


SYSFAIL 


System failure 


7 


APPERR 


Probable application error 


8 


NOTFND 


Item not located 


9 


BADFI^T 


Bad format for call/data 


10 


LOCKED 


Resource/data locked 


11 


MEDIA 


Incorrect media, CRC error 


12 


ALREADY 


Resource/action already taken/done/exists 


13 


UNK 


Unclassified 


14 


CAN'T 


Can't perform requested action 


15 


TIME 


Timeout 


Action Definitions 




Value 


iMnemonic 


Description 


1 


RETRY 


Retry immediately 


2 


DLYRET 


Delay and retry 


3 


USER 


Bad user input - get new values 


4 


ABORT 


Terminate in an orderly manner 


5 


PANIC 


Terminate immediately 


6 


IGNORE 


Ignore error 


7 


INTRET 


Retry after user Intervention 
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Locus Definitions 

Value Mnemonic Description 

1 UNK Unknown 

2 DISK Random access device such as a disk 

3 NET Network 

4 SERDEV Serial device 

5 MEM Memory 
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Purpose 

DosError allows a process to disable user notification (from OS/2) on 
hard errors and program exceptions. 

Calling Sequence 

EXTRN DosError: FAR 

PUSH WORD Flag ; Act ion flag 

CALL DosError 



Where 



Flag 



is a bit field defined as shown below, 
are reserved and must be 0. 



The unused high-order bits 



xxxxxxxxxxxxxxxO 

xxxxxxxxxxxxxxxl 
xxxxxxxxxxxxxxOx 
xxxxxxxxxxxxxxlx 



disable hard error popups 

(fail requests) 
enable liard error popups 
enable exception popups 
disable exception popups 



Returns 

IF AX = 0 then NO error 
ELSE AX = error code 



Family API Considerations 

Some options operate differently in the DOS mode than they do in the 
OS/2 mode. Therefore, the following restriction applies to DosError 
when coding in the DOS mode: 

For Flags, a value of 0000 will cause all subsequent INT 24's to be 
failed until a subsequent call with a value of 1 is issued. 
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Remarks 

The default situation is both hard error pop-ups and exception 
pop-ups are enabled, if DosError is not issued. DosError allows an 
OS/2 process to disable user notification if a program (or untrapped 
numeric processor) exception occurs. If end user notification is disa- 
bled, and, if one of these exceptions occurs, the process is termi- 
nated. 
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Purpose 

DosExecPgm allows a program to request another program to 
execute as a child process. The requestor's process continues to 
execute asynchronously to the new program. 

Calling Sequence 

EXTRN DosExecPgm: FAR 

PUSH@ OTHER ObjNameBuf 

PUSH WORD ObjNameBufL 

PUSH WORD ExecFlags 

PUSH@ ASGIIZ ArgPointer 

PUSH@ ASCIIZ EnvPointer 

PUSH@ DWORD ReturnCodes 

PUSH@ ASCIIZ PgmPointer 

CALL DosExecPgm 

Where 

ObjNameBuf 

is a buffer where the name of the object that contributed to the 
failure of DosExecPgm Is returned. 

ObJNameBufL 

is the length, in bytes, of the buffer described by ObjNameBuf. 
ExBcFlags 

Is an indicator that the requested program is to execute asynchro- 
nous to the requestor, with/without tracing, or in a session sepa- 
rate from the parent. 

Value Definition 

If value = 0 

the program executes synchronously to the parent process. 
The termination code and result code is stored in the 
two-word structure ReturnCodes. 



;Object name buffer (returned) 

; Length of object name buffer 

; Execute asynchronously/trace 

jArgument string 

; Environment string 

;Termi nation codes (returned) 

; Program filename 
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If value = 1 

the program executes asynchronously to the parent process. 
When the requested program terminates, its ResultCode is 
discarded. The Process ID is stored in the first word of the 
two-word structure ReturnCodes. 

If value = 2 

the program executes asynchronously to the parent process. 
When the requested program terminates, Its ResultCode is 
saved for interrogation by a DosCwait request. The Process 
ID is stored in the first word of the two-word structure 
ReturnCodes. 

If value = 3 

the program executes under conditions for tracing. The 
parent process is the debugger and the child is the process 
to be debugged. 

If value = 4 

the program executes asynchronously to the parent process 
detached from the parent process session. When a process 
is started as a detached process it is not affected if the 
parent process is stopped. The detached process is treated 
as an orphan of the parent process. A program executed 
with this option executes in the baclcground. It should not 
require any input from the keyboard or output to the screen 
other than VioPopUps. It should not issue any VIO, KBD or 
MOU calls. 

If value = 5 

the program is loaded into storage and made ready to 
execute, but Is not placed into execution until the session 
manager thaws the process. 

Some memory is consumed for uncollected result codes. Issue 
DosCwait to release this memory. If result codes are not col- 
lected, then ExecFlags = 0 or 1 should be used. 

ArgPointer 

is a set of argument strings passed to the target program. These 
strings represent "command parameters" for the program as 
opposed to the "environment parameters." 
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The convention used by CMD.EXE is that the first of these strings 
is the program name (as entered after the command prompt or 
found in a batch file) and the second string is the remaining char- 
acters from the command prompt. 

If no argument string is passed to the program, push a 
double-word of Os. 

EnvPolnter 

is a block of text strings that are passed to the program. These 
strings convey configuration parameters and represent the combi- 
nation of the current value of all "Set Symbols" for the current 
program. 

When an Indicated program gets control, it receives: 

• A pointer to a copy of the environment 

• A string of the fully qualified path of the filename of the 
program being started 

• A copy of the argument strings passed to the target program. 

A coded example of this follows: 

eo: ASCIIZ string 1 ; environment string 1 
ASCIIZ string 2 ; environment string 2 

ASCIIZ string n ; environment string n 
Byte of 0 

po: ASCIIZ ; string of filename 

; of program to run. 

ao: ASCIIZ ; argument string 1 

ASCIIZ ; argument string 2 

Byte of 0 

The beginning of the environment segment is "eo" and "ao" is the 
offset of the first argument string in that segment. Register BX 
contains "ao" on entry to the target program. The environment 
strings have the form parameter = value. A 0 value for the 
address of EnvPointer causes the newly created process to inherit 
the unchanged parent's environment. 
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ReturnCodes 

is a structure where the Process ID or termination code and the 
result code, indicating the reason for the child's termination are 
returned. 

For an asynchronous request the first word is the process ID of the 
child process. 

For a synchronous request the first word Is a termination code fur- 
nished by the system that describes why the child terminated. The 
values returned and their meanings are: 

0 = EXIT (normal exit) 

1 = Hard error abort 

2 = Trap operation 

3 = Unintercepted DosKillProcess. 

The second word is used to pass the ResultCode specified by the 
terminating process on its last DosExit call. 

PgmPolnter 

is the name of the file that contains the program to be executed. 
When the environment is passed to the target program, this name 
is copied into "po" in the above environment description. 

If the string appears to be a fully qualified path (for example: con- 
tains a : (colon)in the second position and/or contains a "\") the 
program is loaded from the indicated drlve:dl rectory. If neither of 
these are true, and this filename is not found in the current direc- 
tory, each drive:di rectory specification in the path defined in the 
current program's environment is searched for this file. Any 
extension (.xxx) is acceptable for a program filename. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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Family API Considerations 

Some options operate differently in the DOS mode than they do in the 
OS/2 mode. Therefore, the following restrictions apply to 
DosExecPgm when coding In the DOS mode: 

• If ExecFlags = non-zero. DosExecPgm returns the following error 
code, ERROR_INVALID_DATA. 

• This field must be set to 0. This value will not be related to the 
PID of the program being executed. 

Remarlcs 

The target program is located and loaded into storage if necessary. 
A process is created and executed for the target program. If asyn- 
chronous execution is not indicated, the requesting process 
waits pending completion of the target program 

The new process is created with an address space separate from its 
parent, that is, a new LDT built for the process. 

The new process inherits all the file handles and pipes from its parent 
without the same access rights. Files are inherited except those 
opened with no inheritance indicated. Pipes are inherited. 

The parent process has control of the meanings of standard input, 
output, and error. The parent can write a series of records to a file, 
open the file as standard input, open a listing file as standard output, 
and execute a sort program that takes input from standard input and 
writes to standard output. 

To test whether a program is running detached, use the following 
method. Issue a video call, (for example, VioGetAnsI). If the call is 
not issued within a video popup and the process is detached, the 
video call will return error code ERROR VIO DETACHED in AX. 
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Purpose 

DosExit is issued when a thread completes executing. The current 
thread or probess ends. 

Calling Sequence 

EXTRN DosExit: FAR 

PUSH WORD ActionCode ; Indicates end thread or process 

PUSH WORD ResuUCode ;Resu1t Code to save for DosCwait 

CALL DosExit 

Where 

ActionCode 

Indicates whether to terminate the process and ail its threads. 

If value = 0 

the current thread ends. 
If value = 1 

all threads in the process end. 

Resu/tCocfe 

is the program's completion code. It is passed to any thread that 
issues DosCwait for this process. 

Returns 

None 

Family API Considerations 

Some options operate differently in the DOS mode than they do in the 
OS/2 mode. Therefore, the following restrictions apply to DosExit 
when coding in the DOS mode: 

There is no thread support in DOS 3.3, therefore DosExit exits the cur- 
rently executing program. 

If ActionCode = 0 this option is Ignored. It is equivalent to an 
ActionCode = 1. 
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Remarks 

If the ending thread is the last thread in a process, or if the request 
indicates to terminate all threads In the process, the process also ter- 
minates. All but one thread is terminated and that thread executes 
routines in the DosExitList list. 

When this is completed, this thread and all other resources owned by 
this process are released. Since the system can start threads on 
behalf of an application, a request intended to terminate a process 
must specify ActionCode = 1 regardless of how many threads the 
application author believes to be executing. 

Do not terminate thread 1 without terminating the process. When 
thread 1 ends, any monitors or signal processing routines set for this 
process will end. To prevent unpredictable results, specify action 
code = 1 when ending thread 1 to ensure the process ends. 
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Purpose 

DosExitCritSec re-enables tliread switching for tlie current process. 
Calling Sequence 

EXTRN DosExitCritSec: FAR 
CALL DosExitCritSec 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

DosExitCritSec executes after DosEnterCritSec and restores normal 
thread switching to the threads in a process. 

A count of the number of outstanding DosEnterCritSec requests is 
maintained. The count is increased on DosEnterCritSec requests and 
decreased on DosExitCritSec requests. A DosExitCritSec request 
does not cause normal thread dispatching to restore while the count 
is greater than zero. This count is maintained in a word and if this 
word is decremented below zero (underflow), the count is set to zero, 
an error is returned, and the operation does not execute. 
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Purpose 

DosExitList maintains a iist of routines tliat execute wlien the current 
process ends. 

Calling Sequence 

EXTRN DosExitList: FAR 

PUSH WORD Function ; Function request code 

PUSH DWORD RtnAddress ;Routine address 

CALL DosExitList 

Where 

Function 

indicates wlietlier to add or remove a routine address from tlie 
list. Tlie values and their meanings are: 

1 = Add address to termination iist 

2 = Remove address from termination iist 

3 = Termination processing complete, transfer to next 
address on termination list. 

RtnAddress 

is the routine to be executed. 

Returns 

IF AX s= 0 then NO error 
ELSE AX = error code 

Remarks 

DosExitList defines a routine that gets control when a process com- 
pletes executing. Multiple routines can be defined to receive control 
when a process terminates. For each process, OS/2 maintains a list 
of routines. When the process terminates, it transfers control to each 
address on the list. If there are multiple addresses on the list, each 
get control in an indeterminate order. 
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DosExitList can be used in a library module to free resources or 
semaphores left busy when a client program ends. Before trans- 
ferring control to the routines on the termination list, OS/2 resets the 
stack to its Initial value. Transfer is by way of a JMP instruction. The 
routine must be In the address space of the terminating process. 
When complete the termination routine at that address issues 
DosExitList with Function = 3. Control is then transferred to another 
address on the exit list. When all addresses are serviced, the 
process completes exiting. 

It is important that the exit routines be short and fail-safe. If a routine 
does not issue a DosExitList Function 3, the process stops, and 
OS/2 prevents termination. 

When DosExitList routines execute, the process is in a state of partial 
termination. To insure good response there should be minimum 
delay in allowing termination to complete. All threads except the one 
executing the DosExitList routines are destroyed. 

Most OS/2 system calls are valid In a DosExitList routine, however, 
certain functions such as DosCreateThread and DosExecPgm are not. 
When the exit list routine receives control, the first parameter on the 
stack (located at SS:SP+4) contains an indicator that explains why 
the process ended. The values provided are the same as those pro- 
vided by the system as termination codes on DosCwait or 
DosExecPgm requests. The values returned and their meanings are: 

0 = EXIT (normal exit). 

1 = Hard error abort 

2 = Trap operation 

3 = Un-intercepted DosKIIIProcess. 
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Purpose 

DosFileLocks locks and unlocks a range In an opened file. 
Calling Sequence 

EXTRN DosFileLocks: FAR 

PUSH WORD FileHandle -.File handle 

PUSH@ OTHER UnLockRange ;UnLock range 

PUSm OTHER LockRange ;Lock range 

CALL DosFileLocks 

Where 

FileHandle 

Is the file handle. 

UnLockRange 

is the range to be unlocked, specified as a doubie-word pair. 

The first double-word is the FileOffset where the locked area 
begins. 

The second double-word Is the RangeLength. 
A null pointer to UnLockRange specifies unlocking Is not required. 
LockRange 

Is the range to be locked, specified as a double-word pair. 

The first double-word Is the FileOffset where the locked area 

begins. 

The second double-word is the RangeLength. 

A null pointer to LockRange specifies locking is not required. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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Remarks 

DosFileLocks provides a meclianism for excluding other processes 
read/write access to regions of a file. DosFileLocks is used when a 
file is opened using deny read or deny none sharing modes or when 
the file is opened for read/write and deny write sharing mode only. 
The locked regions can be anywhere in the logical file. 

Locking beyond end-of-file Is not an error. A region should only 
remain locked for a short time. Duplicating the handle duplicates 
access to the locked regions. Access to the locked regions is not 
duplicated across the DosExecPgm system call. The method for 
using locks is to lock the desired region and examine the error code. 

If unlocking is specified, the function first unlocks the specified area 
using UnLockRange. After UnlockRange is processed, then the 
locking of a range (If specified via LockRange) is done. 

A lock range must be cleared of any locked subranges or locked 
overlapping ranges. When a file with locks closes, the locks release 
in no defined order. When an open file containing an open file with 
locks terminates, the file closes and the locks release. 
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Purpose 

DosFindClose closes the association between a directory handle and 
a DosFlndFlrst or DosFindNext directory search function. 

Calling Sequence 

EXTRN DosFindClose: FAR 

PUSH WORD DirHandle ; Directory search handle 
CALL DosFindClose 

Where 

DirHandle 

is the handle previously associated with a DosFlndPirst by the 
system, or used with a DosFindNext directory search function. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

When DosFindClose is issued, a subsequent DosFindNext call for the 
closed DirHandle will fail unless an intervening DosFindFirst has 
been issued specifying DirHandle. 
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Purpose 

DosFindFirst finds the first set of fiienames tliat matcli a given file 
specification. 

Calling Sequence 



EXTRN 


DosFindFirst: FAR 




PUSH@ 


ASCIIZ 


Fi 1 eName 


;File path name 


PUSH© 


WORD 


Di rHandl e 


; Directory search handle 


PUSH 


WORD 


Attri bute 


; Search attribute 


PUSH@ 


OTHER 


ResultBuf 


; Result buffer 


PUSH 


WORD 


Resul tBuf Len 


; Result buffer length 


PUSH@ 


WORD 


SearchCount 


; Number of entries to find 


PUSH 


DWORD 


0 


; Reserved (must be 0) 


CALL 


DosFindFirst 





Where 

FileName 

Is tlie patii name of the files to be found. 
DIrHandle 

is the directory handle associated by the systenn with a specific 
request. A DIrHandle value of 0001 H is defined as always avail- 
able. A DirHandle value of FFFFH allocates a handle to the user. 
The handle is returned by overwriting the FFFFH. Reuse of this 
DirHandle in another DosFindFirst closes the association with the 
previous DosFindFirst and opens a new association. 

Attribute 

is the attribute used to search for the file. 

If Attribute is 0, normal file entries are found. Entries for subdirec- 
tories, hidden, and system files, are not returned. 

If Attribute is set for hidden or system files, or directory entries, it 
is considered an inclusive search. All normal file entries plus all 
entries matching the specific attributes are returned. Set attribute 
to hidden -I- system + directory (all three bits on) to look at all 
directory entries except the volume label. 
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Attribute cannot specify the volume label. Volume labels are 
queried using DosQFslnfo. 

ResultBuf 

is where the Information is returned. It contains one or more 
entires of the following format: 



2 bytes - 


File date of creation 


2 bytes - 


File time of creation 


2 bytes - 


File date of last access 


2 bytes - 


File time of last access 


2 bytes - 


File date of last write 


2 bytes - 


File time of last write 


2 bytes - 


File end of data (low word) 


2 bytes - 


File end of data (high word) 


2 bytes - 


file allocation (low word) 


2 bytes - 


file allocation (high word) 


2 bytes - 


File attribute 


1 byte - 


Length of of ASCIIZ name string 


n bytes - 


ASCIIZ name string. 



This information Is as accurate as the most recent DosClose or 
DosBufReset. 

Re8ultBufLen 

is the length of ResultBuf. 

SearchCount 

is the number of matching entries requested in ResultBuf. On 
return, this field contains the number of entries placed into 
ResultBuf. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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Family API Considerations 

Some options operate differently In the DOS mode than they do In 
OS/2 mode. Therefore, the following restrictions apply to 
DosFindFirst when coding In the DOS mode: 

DIrHandle must always equal one or FFFFH on the initial call to 
DosFindFirst. Subsequent calls to DosFindFirst must have a 
DirHandle of 1 unless a DosFindClose had been Issued: in that case, 
one or FFFFH is allowed. 

Remarks 

DosFindNext uses the directory handle to repeat the related 
DosFindFirst. 

To find all files that match a given pattern, issue DosFindFirst to find 
the first file. Repeatedly issue DosFindNext to find the next file 
(specify the DirHandle returned by DosFindFirst) until the return code 
Indicates ERROR_NO_MORE_FILES is returned. Finally, issue 
DosFindClose to close the directory handle. 

The time is mapped in the bits as follows: 

15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 
hhhhhmmmmmmxxxxx 

Where: 

hh binary number of hours (0-23) 

mm binary number of minutes (0-59) 

XX binary number of two-second Increments 

Note: The time is stored with the least significant byte first. 

The mm/dd/yy are mapped in the bits as follows: 

15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 
yyyyyyymmmmddddd 

Where: 

mm 1-12 
dd 1-31 

yy 0-119(1980-2099) 
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The date is stored with the least significant byte first. 

The file name in FileName can contain global characters. 

File date/time of creation and file date/time of last access are not 
supported in this release and are returned as zeros. 
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Purpose 

DosFindNext locates the next set of directory entries tliat match the 
name specified in the previous DosFlndFlrst or DosFindNext call. 

Calling Sequence 

EXTRN DosFindNext: FAR 

PUSH WORD DirHandle 

PUSH@ OTHER ResultBuf 

PUSH WORD ResuUBufLen 

PUSH@ WORD SearcliCount 

CALL DosFindNext 

Where 

DirHandle 

Is the handle associated with a previous DosFlndFlrst or 
DosFindNext function call. 

ResultBuf 

is where the file system returns the results of the qualified direc- 
tory search. The Information returned is as accurate as the most 
recent DosClose or DosBufReset. 



2 bytes - 


File date of creation 


2 bytes - 


File time of creation 


2 bytes - 


File date of last access 


2 bytes - 


File time of last access 


2 bytes - 


File date of last write 


2 bytes - 


File time of last write 


2 bytes - 


File end of data (low word) 


2 bytes - 


File end of data (high word) 


2 bytes - 


File allocation (low word) 


2 bytes - 


File allocation (high word) 


2 bytes - 


File attribute 


1 byte - 


Length of ASCIIZ name string 


n bytes - 


ASCIIZ name string. 



•.Directory handle 

; Result buffer 

; Result buffer length 

; Number of entries to find 
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ResultBufLen 

is the length of ResultBuf. 

SearchCount 

is where the number of matching entries requested in ResultBuf 
are located. The file system stores the number of entries actually 
returned. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Family API Considerations 

Some options operate differently in the DOS mode than they do in 
OS/2 mode. Therefore, the following restriction applies to 
DosFindNext when coding in the DOS mode: 

• DIrHandle must always equal 1. 
Remarks 

An error code returns if no matching files are found. 

For more information refer to "DosFlndFirst - Find First Matching 
File" on page 2-59. 

File date/time of creation and file date/time of last access are not 
supported in this release and are returned as zeros. 
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Purpose 

DosFlagProcess allows one process to set an "external event" flag 
for another. 

Calling Sequence 

EXTRN DosFlagProcess: FAR 

PUSH WORD ProcessID 

PUSH WORD Act i encode 

PUSH WORD Flagnum 

PUSH WORD Flagarg 

CALL DosFlagProcess 

Where 
ProcessID 

Is the ID of the process or root process of the process tree, for 
which the flag is to be set. 

ActlonCode 

indicates whether to flag descendant processes in addition to the 
process Indicated by ProcessID. 

If value = 0 

the indicated process and all its descendants processes 
(except detached processes), will be flagged. The indicated 
process must be the current process, or must have been 
created by the current process as a non-detached process. If 
the indicated process terminates, its descendants are still 
flagged. 
If value = 1 

only indicated process will be flagged. Any process can be 
specified. 

Flagnum 

Is the number of the flag to be set: 

0 = flag A 

1 = flag B 

2 = flag C 



; Process ID to flag 

; Indicate to flag descendants 

;F1ag number 

:F1ag argument 
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Flagarg 

is an argument passed to indicated processes. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

User flags are signals whose action Is defined by the user. By 
default, a user flag is ignored by a process. A process can use 
DosSetSlgHandler to install a signal handler for the signal number 
corresponding to the user flag (SIGPFA is the signal number corre- 
sponding to user flag A etc.). The process is alerted, via the signal 
mechanism, when it has been flagged. The process will then be 
alerted, via the signal mechanism, when it has been flagged. A 
process can also specify that the flag action is to be ignored and that 
an error code is to be returned to the flagger. 
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Purpose 

DosFreeModule frees the reference to a dynamic link module for a 
process. Wlien the dynamic iinl< module is no longer needed by any 
process, the module is freed from system memory. 

Calling Sequence 

EXTRN Dos FreeModul e : FAR 

PUSH WORD ModuleHandle ;Modu1e handle 
CALL DosFreeModule 

Where 
ModuleHandle 

is the handle returned by DosLoadModule for the dynamic link 
module to be freed. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

The module Identified by the handle must be loaded through 
DosLoadModule. An error is returned if the handle is invalid. 

When a function completes, the module handle is no longer valid and 
is not used to reference the dynamic link module. Procedure entry 
addresses returned for this module are also no longer v^lid and 
cause a protection fault if they are invoked. 
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Purpose 

DosFreeSeg deallocates a memory segment. 
Calling Sequence 

EXTRN DosFreeSeg: FAR 

PUSH WORD Selector -.Selector 
CALL DosFreeSeg 

Where 

Selector 

is the selector of the segment to be freed. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Family API Considerations 

Some options operate differently in the DOS mode than they do in 
OS/2 mode. Therefore, the following restriction applies to 
DosFreeSeg when coding in the DOS mode: 

If DosFreeSeg is issued on a CSAIiased segment it deallocates the 
associated memory. This is inconsistent with the OS/2 mode, 
because DosFreeSeg must be performed on both the original and 
CSAIiased selectors. 
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Remarks 

DosFreeSeg is designed to free memory segments: shared segments, 
unshared segments, memory allocated by DosAllocSeg or 
DosAllocHuge and CS alias created by DosCreateCSAIias. 

The CS alias selector is not affected if the data selector for the 
aliased segment is passed to DosFreeSeg. Procedures in this 
segment can continue to be referenced. 

DosFreeSeg decrements the reference count for shared segments. 
When the reference count is 0, the memory is deallocated. 
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Purpose 

DosGetCollate obtains a collating sequence table (for characters OOH 
through FFH) that resides in the country information file. It is used by 
the SORT utility to sort text according to the collating sequence. 



Calling Sequence 

EXTRN DosGetCollate: FAR 



PUSH WORD 
PUSH© OTHER 
PUSH© OTHER 



Length 

Structure 

MemoryBuffer 



PUSH@ WORD DataLength 
CALL DosGetCol 1 ate 



; Length of data area provided 
; Input data structure 
;Data area to contain the 
; collate table 
; Length of table 



Where 
Length 

is the byte length of the data area (MemoryBuffer) provided by the 
caller. A length value of 256 is sufficient. 

Structure 

is a two word input data structure where: 
word 0 

Country Code (0 - default country) 
word 1 

Code Page ID (0 - current process code page). 
MemoryBuffer 

is the area where the collating table is returned. This memory 
area is provided by the caller. The size of the area is provided by 
the input parameter Length and should be at least 256 bytes. If it 
is too small to hold all the available information then as much 
information as possible is provided in the available space (in the 
order in which the data would appear). If the amount of returned 
data does not fill the memory area provided by the caller, the 
unaltered memory is set at 0. The buffer format for the returned 
information follows: 
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1 Byte = sort weight of ASCII (0) 
1 Byte = sort weight of ASCII (1) 

Additional values in collating order: 

1 Byte = sort weight of ASCII (255) 

DataLength 

is where the length In bytes of the collate table Is returned. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

The returned country dependent Information may be for the default 
country and current process code page or for a specific country and 
code page. For more Information "DosSetCp — Set Code Page" on 
page 2-222. 
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Purpose 

DosGetCp allows a process to query the current process code page 
and the prepared system code pages. 

Calling Sequence 

EXTRN DosGetCp: FAR 

PUSH WORD Length ; Length of list 

PUSH@ OTHER CodePageList ;List (returned) 

PUSH@ WORD DataLength ; Length of returned list 

Cal 1 DosGetCp 

Where 

Length 

is the length In bytes (should be at least 2), of CodePageList. 
CodePageUst 

is the area where the code page Information Is returned. If 
CodePageList length is too small to hold all the available informa- 
tion, then as much information as possible is provided In the avail- 
able space. The format of the information returned in this list is: 

1 word = Current process code page 

N words = Other prepared system code pages. 

DataLength 

is the length in bytes of the data returned. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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Family API Considerations 

Some options operate differently in the DOS mode than they do in 
OS/2 mode. Therefore, the following restriction applies to DosGetCp 
when coding In the DOS mode: 

The current process code page, and at most one prepared system 
code page Is returned. 

Remarks 

If the process code page identifier was previously set by DosSetCp or 
Inherited by a process. It is returned to the caller. The current 
process code page Identifier is returned by a two byte Input list. 
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Purpose 

DosGetCtrylnfo obtains country dependent formatting information tliat 
resides in tiie country information file. 



Calling Sequence 

EXTRN DosGetCtrylnfo: FAR 



PUSH WORD 

PUSH@ OTHER 

PUSH@ OTHER 

PUSH@ WORD 



Length 
Structure 
MemoryBuffer 
DataLength 



CALL DosGetCtrylnfo 



;Length of data area provided 

; Input data structure 

;Data area to be filled by the function 

; Length of data (returned) 



Where 
Length 

is the byte lengtli of the data area (MemoryBuffer) provided by the 
caller. This length should not be less than 38 bytes. 

Structure 

is a two word input data structure where: 
word 0 

Country Code (0 - default country) 
word 1 

Code Page ID (0 - current process code page). 
MemoryBuffer 

is the area where the country dependent information is returned. 
This memory area is provided by the caller. The size of the area is 
provided by the input parameter Length and should be at least 38 
bytes, if it is too small to hold ail the available information as 
much information as possible is provided in the available space. 
If the amount of data returned is not enough to fill the memory 
area provided by the caller the memory that is unaltered by the 
available data is set at 0. The format of the information returned in 
this buffer is: 
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1 Word - 


Country Code 


1 Word - 


Code Page ID 


1 Word - 


Date format: 0 = mm/dd/yy, 1 = dd/mm/yy, 2 = 




yy/mm/dd 


5 Bytes - 


Currency indicator, null terminated 


2 Bytes - 


Thousands separator, null terminated 


2 Bytes - 


Decimal separator, null terminated 


2 Bytes - 


Date separator, null terminated 


2 Bytes - 


Time separator, null terminated 


1 Byte - 


Bit field for currency format 


BitO - 


1 = currency indicator follows money value and 0 = 




currency indicator precedes money value. 


Bit1 - 


Number of spaces (0 or 1) between currently indi- 




cator and money value. 


Bit 2 - 


When this bit is set, ignore first two bits; currency 




indicator replaces decimal indicator. 


1 Byte - 


Binary number of decimal places used in currency 




indication. 


1 Byte - 


Time format for file directory presentation: 




• Bit 0 = 1 - 24 hour 




• Bit 0 = 0 - 12 hour with "a" or "p". 


2 Words - 


Reserved (set to 0). 


2 Bytes - 


Data list separator, null terminated. 


5 Words - 


Reserved (set to 0). 



DataLength 

is where the length in bytes of the country dependent information 
Is returned. 



Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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Family API Considerations 

Some options operate differently in the DOS mode than they do In 
OS/2 mode. Therefore, the following restrictions apply to 
DosGetCtrylnfo when coding in the DOS mode: 

Not all country information is available in DOS 3.3. 
Remarlcs 

The returned country dependent information may be for the default 
country and current process code page or for a specific country and 
code page. For more Information on code page, see "DosSetCp - 
Set Code Page" on page 2-222. 
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Purpose 

DosGetDateTime gets the current date and time maintained by the 
operating system. 

Calling Sequence 

EXTRN DosGetDat eTi me : FAR 

PUSH© OTHER DateTime ;Date/time structure (returned) 
CALL DosGetDateTime 



Where 

DateTime 

is a structure that receives the foliowing data items: 



BYTEO 


-IHour is current hour 


BYTE 1 


-Minute is current minute 


BYTE 2 


-Second is current second 


BYTE 3 


-i-iundredth is current hundredths of a second 


BYTE 4 


-Day is current day 


BYTES 


-Month is current month 


WORD 6 


-Year is current year 


WORD 8 


-TimeZone is minutes from UTC (Universal Time Coor- 




dinate) 


BYTE 10 


-DayofWeel< is the current day of the week. 



Note: The numbers following BYTE and WORD in the description of 
the above structure, represent decimal offset values from the begin- 
ning of the structure. 
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Returns 

AX = 0 

Remarks 

The DayofWeek value is based on Sunday equal to 0. TImeZone is 
the difference In minutes between the current time zone and UTC. 
This number Is positive if it is earlier than UTC and negative If It is 
later than UTC. For eastern standard time, this value Is 300 (5 hours 
earlier than UTC). 

The application need not call this function to obtain the date or time. 
The address of memory containing a continuously updated date and 
time is obtained from the DosGetlnfoSeg function. Applications 
written to the family API cannot depend on the availability of 
DosGetlnfoSeg. 
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Purpose 

DosGetDBCSEv obtains a DBCS (double byte character set) environ- 
mental vector that resides in the country information file. 

Calling Sequence 

EXTRN DosGetDBCSEv: FAR 

PUSH WORD Length 
PUSH@ OTHER Structure 
PUSH© OTHER MemoryBuffer 

CALL DosGetDBCSEv 

Where 

Length 

is the byte length of the data area (MemoryBuffer) provided by the 
caller. This value should be at least 10. 

Structure 

is a two word input data structure where: 
word 0 

Country Code (0 - default country) 
word 1 

Code Page ID (0 - current process code page). 
MemoryBuffer 

is where the country dependent information for the DBCS environ- 
mental vector Is returned. This memory area is provided by the 
caller. The size of the area is provided by the input parameter 
Length. If it is too small to hold all the available information then 
as much information as possible is provided in the available 
space The format of the information returned in this buffer is: 

2 Bytes - First range definition for DBCS lead byte values 

• Byte 1 = Binary start value (inclusive) for range one 

• Byte 2 = Binary stop value (inclusive) for range 
one 



;Lengtli of data area provided 
; Input data structure 
;Data area to contain 
; the information 
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2 Bytes 



Second range definition 



• Byte 1 = Binary start value for range two 

• Byte 2 = Binary stop value for range two 



2 Bytes 



Nth range definition 



Byte 1 = Binary start value for Nth range 
Byte 2 = Binary stop value for Nth range 



2 Bytes Two bytes of binary 0 terminate list. 
For example: 

DB 81H,9FH 
DB E0H.FCH 
DB 0.0 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

The returned DBCS environmental vector may be for the default 
country and current process code page or for a specific country and 
code page. For more information on code page see "DosSetCp - 
Set Code Page" on page 2-222. 
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Purpose 

DosGetEnv returns the address of the process environment string for 
the current process. 

Calling Sequence 

EXTRN DosGetEnv: FAR 

PUSH@ WORD EnvSegment ;Se1ector (returned) 

PUSHe WORD CmdOffset :Coiiinand line offset (returned) 

CALL DosGetEnv 

Where 

EnvSegment 

is where the seiector for the environment segment is returned. 
CmdOffset 

is where the offset to the command iine within the environment 
segment is returned. 

Returns 

iF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

This call can be used by library routines that need to determine the 
environment for the current process. 
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Purpose 

DosGetHugeShift returns a shift count used to derive the selectors 
that address memory aliocated with DosAllocHuge. 

Calling Sequence 

EXTRN DosGetHugeShift: FAR 

PUSH@ WORD ShiftCount :Shift Count (returned) 
CALL DosGetHugeShift 

Where 

ShiftCount 

is where the shift count is returned. 

Returns 

AX = 0 

Remarks 

To compute the next sequential selector in a huge memory area, take 
the value 1, shift It left by the number of bits specified in shift count. 
Use the resulting value as an increment to add to the previous 
selector (using the selector returned by DosAllocHuge as the first 
selector) Refer to "DosAllocHuge — Allocate Huge Memory" on 
page 2-2 for more information regarding selector use. 
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Purpose 

DosGetlnfoSeg returns the address of a global and process local data 
segment used to determine the value of several items of general 
information. 

Calling Sequence 

EXTRN DosGetlnfoSeg: FAR 

PUSH? WORD Global Seg ; Global segment (selector) 

PUSH@ WORD Local Seg ; Local segment (selector) 

CALL DosGetlnfoSeg 

Where 

GlobalSeg 

is where the selector for the global information segment is 
returned. 

LocalSeg 

is where the selector for the local information segment is 
returned. 

Returns 

AX = 0 
Remarlcs 

Items of general Interest are kept in the global information segment. 
Items of information specific to a particular process are kept in the 
local information segment. This information can be directly read by 
the application program. Both these segments are defined as 
read/only segments. The application program cannot modify this 
data. 
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Format of the Global Information Segment 



Data 






item 




Size 


TIME 


DD 


Time from 1-1-1970 in seconds 




DD 


Milliseconds 




OB 


Hours 




DB 


Minutes 




DB 


Seconds 




DB 


Hundredths 




DW 


Timezone (minutes from UTC, -1 = timezone is 
undefined) 




DW 


Timer interval (units = 0.0001 seconds) 


DATE 


DB 


Day 




DB 


Montii 




DW 


Year 




DB 


Day-of-weeic (0 = Sunday, 1 = Monday,.. .etc.) 


VERSION 


DB 


Major version number 




DB 


Minor version number 




DB 


Revision letter 


SYSTEM 


DB 


Current foreground session 


STATUS 








DB 


Maximum number of sessions 




DB 


Shift count for huge segments 




DB 


OS/2 mode only indicator (0 = DOS mode and 

OS/2 mode, 1 = OS/2 mode only) 




DW 


PID of last process to do a KbdCharIn or 
KbdGetFocus in foreground session. 
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Data 
Item 

SCHEDULER DB 
FARMS 

DB 
DW 
DW 

BOOT DRIVE DW 

SYSTEM DB 

TRACE 

FACILITY 

TRACE 

FLAGS 



Size 

Dynamic variation flag (=1 if enabled, = 0 if 
absolute.) 

Maximum wait (seconds) 
Minimum timeslice (milliseconds) 
Maximum timeslice (milliseconds) 
Boot drive number (1 = A, 2 = B,...etc.) 
32 - System Trace Major Code flag bits. Each 
bit corresponds to a trace major code from OOH 
to FFH. The most significant bit (left-most) of 
the first byte, corresponds to major code OOH. 
Bit=0, trace disabled; Bit=1, trace enabled. 
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Format of the Local Information Segment 
Data 

Item Size 

MISC DW Current process ID 

DW Process ID of parent 
DW Priority of current thread 

• High-Order byte = Priority class 

• Low-Order byte = Priority level 
DW Thread ID of current thread 

DW Session 
DW Unused 

DW Current process has keyboard focus. (-1 

implies yes, 0 implies no) 
DB Current process requires DOS mode. (=1 

implies requires DOS mode). 



The application program must be careful when referencing the date 
and/or time fields in the Global Information Segment. A timer inter- 
rupt can be received by the system in between the instructions that 
read the individual fields, changing the data in these fields. For 
example, if the time is currently 11:59:59 on Tuesday, 6/2/87, the 
program can read the hours field ( 23). A timer interrupt can now be 
received, changing the time to 12:00:00 on Wednesday, 6/3/87. The 
program will now read the rest of the time field (0 minutes) and the 
date field. The program would then think the current time and date is 
11:00:00 on Wednesday, 6/3/87, which is incorrect. 

The application program should read all time and date fields it is 
interested in as quickly as possible. It can then compare the least 
significant time field it is interested in (milliseconds, hundredths, 
seconds, or minutes) against the current value in the Global Informa- 
tion Segment. If the value has not changed, the rest of the informa- 
tion is valid. If the value has changed, the program time and/or date 
inforrhation should be read again, since the information was updated 
while the program was reading it. 
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Purpose 

DosGetMachineMode returns the current mode of the processor, 
whether the processor is running in the DOS mode or the OS/2 mode. 
This allows an application to determine whether a dynamic lini< call is 
valid or not. 

Calling Sequence 

EXTRN DosGetMachI neMode : FAR 

PUSH© BYTE Machi neMode ;Byte to receive mode 
CALL DosGetMachineMode 

Where 

MachineMode 

Is where the value to indicate the current processor mode is 
returned. This value may be: 

0 = DOS mode 

1 = OS/2 mode 

Returns 

AX = 0 

Remarks 

All dynamic link calls are available to an application if the 
MachineMode values indicate the program is in OS/2 mode. This 
method provides a self-tailoring application that allows the applica- 
tion to adapt to the execution environment by limiting or enhancing 
the functions it provides. 

If the MachineMode values indicate the program is in DOS mode, the 
application is limited to a subset of dynamic link calls listed in the 
Family API. 
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Purpose 

DosGetMessage retrieves a message from a message file and inserts 
variable information into the body of the message. 



Catling Sequence 

EXTRN DosGetMessage: FAR 

PUSH@ OTHER IvTable 

PUSH WORD IvCount 

PUSH@ OTHER DataArea 

PUSH WORD DataLength 

PUSH WORD MsgNumber 

PUSH© ASCIIZ FileName 

PUSH@ WORD MsgLength 

CALL DosGetMessage 



; Table of variables to insert 

; Number of variables 

;Message buffer 

•.Length of buffer 

; Number of the message 

;Message path and file name 

; Length of message (returned) 



Where 

IvTable 

is a list of double-word pointers. Each pointer points to an ASCIIZ 
or null-terminated DBCS string (variable insertion text). 0 to nine 
strings can be present. 

IvCount 

Is 0-9, the count of variable insertion text strings. If IvCount is 0, 
IvTable is ignored. 

DataArea 

is where the requested message is returned. If the message is 
too long to fit in the caller's buffer, as much of the message text 
will be returned as possible, with the appropriate error return 
code. 

DataLength 

is the length (in bytes) of the user's storage area. 

MsgNumber 

is the message number requested. 
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FileName 

is the optional drive and path, and file name of the file, where the 
message can be found. If messages are bound to the .EXE file 
using MSGBIND utility, then filename is the name of the message 
file from which the messages will be extracted. 

MsgLength 

is where the length in bytes, of the message is returned. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Family API Considerations 

Some options operate differently in the DOS mode than In OS/2 
mode. Therefore, the following restriction applies to DosGetMessage 
when coding In the DOS mode: 

If the message file name is not a fully qualified name, 
DosGetMessage searches the root directory of the default drive for 
the message file, instead of the root directory of the startup drive. 

Remarks 

If IvCount is greater than 9, DosGetMessage returns an error that 
indicates IvCount is out of range. If the numeric value of x in the %x 
sequence for %1-%9 is less than or equal to IvCount, text insertion 
by substitution for %x, is performed for all occurrences of %x in the 
message. Otherwise text insertion is ignored and the %x sequence 
is returned in the message unchanged. Text insertion Is performed 
for all text strings defined by IvCount and IvTable. 

Variable data insertion is not dependent on blank character delim- 
iters nor are blanks automatically inserted. 

For warning and error messages, the message ID (seven alphanu- 
meric characters consisting of a three-character component ID con- 
catenated with a four-digit message number) followed by a colon and 
a blank character are returned to the caller as part of the message 
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text. (DosGetMessage determines the type of message based on the 
message classification generated in the output file of the MKMSGF 
utility). 

The following is an example of a sample error message returned with 
the message ID: 

SYS010Q: File not found 

DosGetMessage retrieves messages previously prepared by the 
utility MKMSGF to create a message file, or MSGBIND to bind a 
message segment to an .EXE file. DosGetMessage tries to retrieve 
the message from RAM in the message segment bound to the .EXE 
program. If the message cannot be found, DosGetMessage retrieves 
the message from the message file on DASD (direct access storage 
device, such as floppy diskette or fixed-disk), if the message cannot 
be found, then DosGetMessage retrieves the message from the 
message file on the fixed disk or diskette. 

If DosGetMessage is unable to find the specified directory path, 
DosGetMessage searches the following directories for the message 
file: 

• Directories listed in the DPATH statement (OS/2 mode only) 

• Directories listed in the APPEND statement (DOS mode, only) 

If a message cannot be retrieved because of a DASD error or file not 
found condition, a default message is placed in the user's buffer area. 
A message is placed in the buffer area based on the following error 

conditions: 

• The message number cannot be found in the message file. 

• The message file cannot be found. 

• The system detected a disk error trying to access the message 
file, or the message file format is incorrect. 

• IvCount is out of range. 

• A system error occurred trying to allocate storage. 

When these conditions occur, the default message allows the applica- 
tion program to issue a message and prompt that enables recovery 
opportunity. 
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The residency of the message in RAM (EXE bound) or on DASD is 
transparent to the caller and handled by DosGetMessage. In either 
case the message is referenced by message number and file name. 

In order for DosGetMessage to be properly resolved, an application 
must be linked with DOSCALLS.LIB. 
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Purpose 

DosGetModHandle returns a handle to a previously loaded dynamic 
link module. 

Calling Sequence 

EXTRN OosGetModHandl e : FAR 

PUSH@ ASCIIZ ModuleName ;Modu1e name string 

PUSH@ WORD ModuleHandle :Modu1e handle (returned) 

CALL DosGetModHandle 

Where 

ModuleName 

contains the dynamic link module name. 

ModuleHandle 

is where the handle for the dynamic link module is returned. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

This interface provides a mechanism for determining whether a 
dynamic link module is loaded. 

The module name must match the name of the previously loaded 
module. If these names do not match, an error code is returned. The 
module name string must contain the 1-8 character module name, not 
the name of the file containing the module. 
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Purpose 

DosGetModName returns the fully qualified drive, path, FileName, 
and extension associated with a referenced module handle. 

Calling Sequence 

EXTRN DosGetModName: FAR 

PUSH WORD ModuleHandle :Modu1e handle 

PUSH WORD BufferLength ; Buffer length 

PUSH© OTHER Buffer ; Buffer (returned) 

CALL DosGetModName 

Where 

ModuleHandle 

is handle of the dynamic linl< module being referenced. 

BufferLength 

is the maximum length of the buffer, in bytes, where the name Is 
stored. 

Buffer 

is the buffer where the fully qualified drive, path, filename, and 
extension of the dynamic link module is returned. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

An error is returned if the buffer is not large enough. 
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Purpose 

DosGetPID returns the current process' process ID (PID), thread ID, 
and the PjD of the process that created it. 

Calling Sequence 

EXTRN DosGetPID: FAR 

PUSH© OTHER Process IDsArea ; Process IDs (returned) 
CALL DosGetPID 

Where 

ProcesslDsArea 

is the area where the various IDs are returned. 

Returns 

AX = 0 

Remarks 

The format of the returned IDs in ProcesslDsArea is illustrated below: 

WORD the current process' process IP 
WORD the current thread ID 
WORD the process ID of the parent. 

The process ID may be used to generate uniquely named temporary 
files, or for communication via signals. 

For an OS/2 mode process only, it is more efficient to obtain these 
variables from DosGetlnfoSeg. 
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Purpose 

DosGetProcAddr returns a far address to a desired procedure within 
a dynamic link module. 

Calling Sequence 

EXTRN DosGetProcAddr : FAR 

PUSH WORD ModuleHandle ; Module handle 

PUSH© ASCIIZ ProcName ;Module name string 

PUSH@ DWORD ProcAddress ; Procedure address (returned) 

CALL DosGetProcAddr 

Where 

ModuleHandle 

is the handle of the dynamic link module where the procedure is 
located. 

ProcName 

is a name string that contains the referenced procedure name. 

DosGetProcAddr for entries within the DOSCALLS module are 
only supported for ordinal references. References to the 
DOSCALLS module by name strings are not supported and will 
return an error. Dynamic link ordinal numbers for DOSCALLS rou- 
tines are resolved by linking with DOSCALLS. LIB. 

ProcAddress 

is where the procedure address is returned. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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Remarks 

If the selector portion of the pointer is null, the offset portion of the 
pointer is an explicit entry number (ordinal) within the dynamic link 
module. A 32-bit address, consisting of a selector and offset, is 
returned for a specified procedure. 
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Purpose 

DosGetPrty gets the priority of a process or thread in the current 
process. 

Calling Sequence 

EXTRN DosGetPrty: FAR 

PUSH WORD Scope 

PUSH@ WORD Priority 

PUSH WORD ID 

CALL DosGetPrty 

Where 

Scope 

is used to define the scope the request wiii have. 
If value = 0 

the priority of the first thread of the indicated process is 
returned. 
If value = 2 

the priority of the indicated thread is returned. 
Priority 

is a word where the base priority of the indicated process or 
thread is placed. The high-order byte of this word is set equal to 
the priority class. The low-order byte is set equal to the priority 
level. 

ID is either a process ID (scope = 0) or a thread ID (scope = 2). 
If this operand is equal to 0, the current process or thread Is 
assumed. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 



; Indicate scope of query 
.•Priority (returned) 
; Process or thread ID 
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Remarks 

If scope = 0 (process) the priority of tlie first thread of a process is 
returned. If that thread has terminated, the 
"ERRORJNVALID_THREADJD" error code will be returned. 

The segment must have been allocated with DosAllocSeg with Flags 
bit 1 (0010b) set. 
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Purpose 

DosGetSeg gets access to a shared memory segment. 
Calling Sequence 

EXTRN DosGetSeg: FAR 

PUSH WORD Selector ; Selector to access 

CALL DosGetSeg 

Where 

Selector 

is used to get access to a segment. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

Any process that gains access to a discardable segment through 
DosGetSeg, may unloci< the segment for discard through calls to 
DosUnlockSeg. For example, a process may allocate a discardable 
segment that is accessed by another process via DosGetSeg. The 
second process may call DosUnlockSeg on that selector until it is 
fully unlocked. The segment may be discarded later in the event 
memory is nearly full. If the first process accesses the segment, 
assuming it is still locked, it will fail. Locking is an attribute of the 
segment, not the processes using the segment. 

The segment must have been allocated with DosAllocSeg with Flags 
bit one (0010b) set. 
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Purpose 

DosGetShrSeg accesses a shared memory segment previously allo- 
cated by another process. 

Calling Sequence 

EXTRN DosGetShrSeg: FAR 

PUSH@ ASCIIZ Name ;Name string 

PUSH@ WORD Selector ; Selector (returned) 

CALL DosGetShrSeg 

Where 

Name 

is the name string associated with the shared memory segment 
to be accessed. The name is an ASCIIZ string in the format of an 
OS/2 filename in a subdirectory called \SHAREMEM\, for 
example, \SHAREMEM\PUBLIC.DAT. 

Selector 

is where the selector for the shared memory segment is returned. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

The reference count for the shared segment is increased. The 
selector returned to the process that initially allocated It will be the 
same as that returned by the DosAllocShrSeg. 
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Purpose 

DosGetVersion returns the OS/2 version number. 
Calling Sequence 

EXTRN DosGetVersion: FAR 

PUSH© WORD VersionWord ; Vers ion number (returned) 
CALL DosGetVersion 

Where 

VersionWotd 

is where the OS/2 version number is returned. The version is 
stored with the minor version first. 

Returns 

AX = 0 

Remarks 

None 
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Purpose 

DosGiveSeg gives another process access to a shared memory 
segment. 

Calling Sequence 

EXTRN DosGiveSeg: FAR 

PUSH WORD CallerSegSelector 
PUSH WORD Process ID 
PUSH@ WORD RecipientSegSelector 

CALL DosGiveSeg 

Where 

Ca//erSegSe/ector 

is the segment selector of the memory segment to be shared. 

ProcessID 

is the process ID of the process to receive access to the shared 
memory segment. 

RecipientSegSelector 

is where the recipient's segment selector to access the shared 
memory segment is returned. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

it is the caller's responsibility to pass the recipient's segment 
selector to the recipient using some form of interprocess communi- 
cation. 

Any process that gains access to a discardable segment through 
DosGiveSeg may unlock the segment for discard through calls to 



; Caller's segment selector 
; Process ID of recipient 
;Recipient's segment selector 
; (returned) 
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DosUnlockSeg. For example, a process may allocate a discardable 
segment and give it to another process by way of DosGiveSeg. The 
second process may then call DosUnlockSeg on that selector until it 
is fully unlocked. The segment may be discarded later in the event 
memory is nearly full, if the first process accesses the segment, 
assuming it is still locked, it will fail. Locking is an attribute of the 
segment and not of the processes using the segment. 

If the memory being given is a huge memory area allocated by 
DosAlloclHuge, the CallerSegSelector must be the same selector as 
that returned by the corresponding DosAlloclHuge request: for 
example, the selector for the first segment of the huge area. The 
returned RecipientSegSelector, which must be passed to the target 
process, is for the first segment in the recipient's address space. The 
recipient process must use DosGetHugeShift and calculate the 
selector values for the remaining segments of the area. 
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Purpose 

DosHoldSignal temporarily disables or enables signal processing for 
the current process. 

Calling Sequence 

EXTRN DosHoldSignal: FAR 

PUSH WORD ActionCode ; Indicate to Disable/Enable Signals 
CALL DosHoldSignal 

Where 
ActionCode 

Indicates to disable or enable signals intended for the current 
process: 

If value = 0 

signals are enabled. 
If value = 1 

signals are disabled. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Family API Considerations 

Some options operate differently in the DOS mode than they do in the 
OS/2 mode. Therefore, the following restriction applies to 
DosHoldSignal when coding in the DOS mode: 

The only signal recognized in the DOS mode is SIGINTR (Ctrl-C). 
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Remarks 

DosHoldSignal with ActionCode = 1 causes signal processing (except 
SIGTERM and the numeric processor errors) to be postponed until a 
DosHoldSignal with ActionCode = 0 Is issued. Any signals that occur 
while processing is disabled are recognized, but not accepted until 
signal recognition is enabled. 

To allow for nesting of requests, a count of the number of outstanding 
DosHoldSignal requests with ActionCode = 1 are maintained. 

DosHoldSignal is used by library routines, subsystems, and similar 
code that lock critical sections or temporarily reserve resources 
needed to prevent a signal from terminating a task. 

Signals can be held for a short period and should be released and 
re-held, if necessary. Their guidelines for proper use are similar to 
hardware interrupt counterparts such as the CLI/STI instructions. 
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Purpose 

DoslnsMessage inserts variable text string information into the body 
of a message. This Is useful when messages are loaded before 
insertion text strings are known. 

Calling Sequence 



EXTRN 


DoslnsMessage: FAR 




PUSH? 


OTHER 


IvTable 


;Table of variables to insert 


PUSH 


WORD 


IvCount 


; Number of variables 


PUSH@ 


OTHER 


Msglnput 


; Address of input message 


PUSH 


WORD 


MsglnLength 


: Length of input message 


PUSH© 


OTHER 


DataArea 


; Buffer address to return message 


PUSH 


WORD 


DataLength 


; Length of buffer (returned) 


PUSH@ 


WORD 


MsgLength 


; Length of updated message 


CALL 


DoslnsMessage 





Where 

IvTable 

is a list of double-word pointers. Each pointer points to an ASCIIZ 
or null terminated DBCS string (variable insertion text). 0 to nine 
strings can be present. 

IvCount 

is 0-9, the count of variable Insertion text strings. If IvCount is 0, 
then IvTable is ignored. 

Msglnput 

is the input message. 

MsglnLength 

is the length In bytes of the input message. 

DataArea 

is the user storage where the system returns the updated 
message. If the message is too long to fit in the caller's buffer, as 
much of the message text as possible will be returned with the 
appropriate error return code. 
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DataLength 

is the length (in bytes) of the user's storage area. 
MsgLength 

is where the actual length in bytes of the message is returned. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarlcs 

If IvCount is greater than 9, DoslnsMessage returns an error indi- 
cating that IvCount is out of range. A default message is also placed 
in the caller's buffer. Refer to "DosGetMessage - System 
Message with Variable Text" on page 2-88 for details on the default 
messages. If the numeric value of x in the %x sequence for %1-%9 
is less than or equal to IvCount, then text insertion, by substitution for 
%x, is performed for all occurrences of %x in the body of the 
message. Otherwise text insertion is ignored and the %x sequence is 
returned unchanged in the message. Text insertion is performed for 
all text strings defined by IvCount and IvTable. 

Variable data insertion does not depend on a blank character delim- 
iter nor are blanlcs automatically inserted. 
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Purpose 

DosKillProcess flags a process to terminate and returns the termi- 
nation code to its parent (If any). 

Calling Sequence 

EXTRN DosKillProcess: FAR 

PUSH WORD ActionCode ; Indicate to flag descendant processes 

PUSH WORD Process ID ;ID of process or root of process tree 

CALL DosKillProcess 

Where 

ActionCode 

indicates whether to flag existing descendant processes in addi- 
tion to the process indicated by ProcesslD. 

If value = 0 

the indicated process plus ail descendant processes (except 
detached processes) are flagged for termination. The indi- 
cated process must be the current process, or it must have 
been created by the current process as a non-detached 
process. If the indicated process is terminated, its descend- 
ants will be flagged for termination. 
If value = 1 

only the Indicated process Is flagged for termination. Any 
process may be specified. 

ProcesslD 

is the process ID of the process or root process, of the process 
tree to be flagged for termination. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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Remarks 

DosKillProcess allows a process to send the termination signal 
SIGTERM to another process or group of processes. The default 
action of the system will be to terminate each of the processes. A 
process may intercept this action by installing a signal handler for 
SIGTERM (refer to "DosSetSigHandler - Set Signal Handler" on 
page 2-243). In such a case the program will clean up its files and 
execute DosExit. If there is no signal handler, the effect on the 
process will be the same as if one of its threads had done DosExit for 
the entire process. All file buffers are flushed and the handles 
opened by the process are closed, but any internal buffers managed 
by programs external to OS/2 will not be flushed. An example of 
such a buffer could be a C language libraries' internal character 
buffer. 

The process' parent will get the "un-intercepted DosKillProcess" 
code returned when it does a DosCwait call. 
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Purpose 

DosLoadModule loads a dynamic link module and returns a handle 
for the module. 

Calling Sequence 

EXTRN DosLoadModule: FAR 

PUSH© OTHER ObjNameBuf 

PUSH WORD ObjNameBufL 

PUSH@ ASCIIZ ModuleName 

PUSH@ WORD ModuleHandle 

CALL DosLoadModule 

Where 
ObjNameBuf 

is a buffer where the name of the object that contributed to the 
failure of DosLoadModule Is returned. 

ObjNameBufL 

is the length, in bytes, of the buffer described by ObjNameBuf. 
li/loduleName 

is a name string that contains the dynamic Wnk module name. 

ModuleHandle 

is where the handle for the loaded dynamic lini< module Is 
returned. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 



; Object name buffer 

; Length of object name buffer 

:Modu1e name string 

;Modu1e handle (returned) 
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Remarlcs 

If the file Is an OS/2 dynamic link module, it is loaded, and a handle 
is returned. This handle must be passed to DosFreeModule to free 
the dynamic link module. This handle may be passed to 
DosGetProcAddr to get the addresses of procedures within the 
module, or passed to DosGetModName to get the fully qualified 
module name. 



The module name string must contain the 1-8 character module 
name. The module is assumed to reside in a file whose name is 
ModuleName.DLL. This file must be within one of the directories 
specified in the library search path. (See configuration statement 
LIBPATH in the IBM Operating System/2 User's Reference.) 

DosLoadModule may not be called from a dynamic library initializa- 
tion routine if the module to be loaded or any module referenced by it 
contains a dynamic link library initialization routine. 
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Purpose 

DosLockSeg locks a discardable segment in memory. 
Calling Sequence 

EXTRN DosLockSeg: FAR 

PUSH WORD Selector ; Selector to lock 
CALL DosLockSeg 

Where 

Selector 

is the selector of the segment to be locked. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

Discardable segments are useful for holding objects that are 
accessed for short periods of time and can be regenerated quickly if 
discarded. Examples are cache buffers for a data base package, 
saved bitmap images for obscured windows, or precomputed display 
images for a word processing application. 

Allocating objects as discardable allows the memory manager to 
reclaim their space when the system is low on memory and they are 
not currently being accessed. 

When a discardable segment is locked, it still can be moved and 
swapped. It can be swapped to disk if necessary, but will not be dis- 
carded until it is unlocked by DosUnlockSeg. 

While locked, a segment may not be discarded. If a segment is dis- 
carded while unlocked, a subsequent DosLockSeg request for that 
segment will return an error code indicating the segment no longer 
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exists. DosRealiocSeg must allocate a fresh copy of the segment, 
and its contents must be regenerated by the caller. 

DosLockSeg and DosUnlockSeg calls may be nested. If DosLockSeg 
is called multiple times to lock a segment the same number of calls 
must be made to DosUnlockSeg to unlock the segment. However, if a 
segment is locked 255 times it becomes permanently locked. Addi- 
tional calls to DosLockSeg and DosUnlockSeg will have no effect on 
the segment's locked state. 

Note that a call to DosAllocSeg with AllocFlags bit 2 (0100B) set or a 
call to DosRealiocSeg, for a segment so allocated, will allocate the 
memory, and perform the same action as a call to DosLockSeg. 

This function is valid only on segments allocated through 
DosAllocSeg with AllocFlags bit two (0100B) set. 
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Purpose 

DosMakePipe creates a pipe. 
Calling Sequence 

EXTRN DosMakePipe: FAR 

PLISH@ WORD ReadHandle ;Read handle (returned) 

PUSm WORD WriteHandle ; Write handle (returned) 

PUSH WORD PipeSize ;Size to reserve for the pipe 

CALL DosMakePipe 

Where 

ReadHandle 

Is wliere thie read handle for tlie pipe is returned. 
WriteHandle 

is wliere the write handle for the pipe is returned. 
PipeSize 

is the storage size, in bytes, to reserve for the pipe. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

Pipes are mechanisms used within a closely related group of proc- 
esses. There are no control, permission mechanisms, or checl<s per- 
formed on operations to pipes. 

When there is insufficient space in a pipe for the data being written, a 
requesting thread blocks until enough data is removed to allow the 
write request to be satisfied. If the parameter size is 0, then the pipe 
is created with a default size of 512 bytes. 
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When all users close the handles, a pipe Is deleted. If two processes 
are communicating by a pipe and the processes reading the pipe 
ends, the next write gets the "write to a broken pipe" error code. 
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Purpose 

DosMemAvail returns the size of tlie largest block of free memory. 
Calling Sequence 

EXTRN DosMemAvail: FAR 

PUSH@ DWORD MemAvallSIze ;S1ze available (returned) 
CALL DosMemAvai 1 

Where 

MemAvailSize 

is where the size of the largest free block of memory is returned. 
Returns 

AX = 0 

Remarks 

DosMemAvail allows an application to determine how heavily used 
system memory is at a particular time. The returned value is a 
"snapshot" which may be valid only at the moment this function is 
issued and can be expected to change at any time due to system 
activity. 
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Purpose 

DosMkDir creates a specified directory. 
Calling Sequence 

EXTRN DosMkDir: FAR 

PUSH© ASCIIZ DirName ;New directory name 

PUSH DWORD 0 ; Reserved (must be 0) 

CALL DosMkDir 

Where 
DirName 

is the ASCIIZ directory path name that specifies a drive. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

If any member of the directory path does not exist, the directory path 
Is not created. On return, a new directory is created at the end of the 
specified path. 
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Purpose 

DosMonClose terminates character device monitoring. All monitor 
buffers associated with this process are flushed and closed. 

Calling Sequence 

EXTRN DosMonClose: FAR 

PUSH WORD Handle ; Handle from DosMonOpen 

CALL DosMonClose 

Where 

Handle 

is the device handle returned from a previous DosMonOpen call. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

A single process may register one or more monitors with a character 
device using the same device handle returned from a previous 
DosMonOpen call. When DosMonClose is issued for a specific, 
opened device handle, all monitors for the current process registered 
with this handle terminate. 

When DosMonClose is issued, the monitor loses access to the device 
data stream. Before issuing DosMonClose, monitor threads issuing 
DosMonRead and DosMonWrite calls should be terminated. 
DosMonRead calls issued after DosMonClose and DosMonWrite calls 
issued after DosMonClose return the errors 
ERR0R_M0N3UFFER_EMPTY and 
ERROR_NOT_ENOUGH_MEMORY, respectively. 
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Purpose 

DosMonOpen gains access to a character device data stream. 
Calling Sequence 

EXTRN DosMonOpen: FAR 

PUSH? ASCIIZ Devname ; Device name (returned) 

PUSH@ WORD Handle ; Handle value (returned) 

CALL DosMonOpen 

Where 

Devname 

is the device name string. 

Handle 

is where the handle for the monitor is returned. This value must 
be passed to DosMonReg to communicate with the device, and is 
passed to DosMonClose to close the connection to the monitor. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

A process must issue DosMonOpen to get a handle to the specified 
device. A single process may register one or more monitors with the 
same or different data stream for one or more character devices. 

Issue DosMonOpen before registering monitors. A process must get 
the handle to each device whose data stream it wishes to monitor. 
I This handle is used by the process to communicate with the device 
driver in subsequent DosMonReg and DosMonClose calls. 

Issue DosMonOpen once for each device. DosMonOpen must be 
issued before monitors are registered through DosMonReg, but does 
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not have to be reissued before each subsequent DosMonReg call to 
register a monitor with the same device. 

When DosMonClose is issued, all monitors in the process registered 
mih the same device (that is, using the same handle) are closed. 
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Purpose 

DosMonRead waits for and moves a data record fronrt the input buffer 
of a registered character device nnonitor and places It In a private 
data area where the monitor can freely access it. 

Calling Sequence 

EXTRN DosMonRead: FAR 

PUSH0 OTHER Bufferl 

PUSH WORD WaitFlag 

PUSH© OTHER DataBuffer 

PUSH@ WORD Bytecnt 

CALL DosMonRead 

Where 

Bufferl 

Is where the monitor Input buffer Is located. 
WaitFlag 

equals 0 if the monitor thread that issues DosMonRead wishes to 
block until a data record Is available in its input buffer. WaitFlag 
equals 1 if the monitor thread that issues DosMonRead does not 
wish to blocl< when its input buffer Is empty. 

DataBuffer 

is the private data area where the data record taken from the 
monitor's input buffer is returned. The length of DataBuffer must 
be the entry value of Bytecnt. 

Bytecnt 

is the length of DataBuffer, on entry to DosMonRead. On the 
return from DosMonRead, Bytecnt specifies the number of bytes of 
data moved. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 



;Monitor input buffer 
;Blocl</Run indicator 
; Buffer into wliich records are read 
; Input/output pann-#bytes 
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Remarks 

Device monitors are part of a data flow path through a device driver. 
They must respond rapidly to insure they do not delay I/O. This is 
especially important in the case of keyboard monitors. 

A monitor process should be written so the threads that read and 
write the monitor data run at a high priority. Threads that read and 
write the monitor data should not perform operations, such as I/O or 
semaphore waits, which may cause considerable delay. A monitor 
process can have threads running at normal priorities to address 
these things. 

Note: Each call to DosMonRead receives a single complete record. 
Multiple or partial records are not supported. 

It is necessary to guarantee all data is cleaned out of the data stream 
at certain times. This is accomplished by flushing the data stream. A 
marlced record or flush record is placed in the data stream by the 
device driver and passes through all monitors in the chain to allow 
them to perform a device-specific, prescribed activity. Placement of 
new data records in the data stream is suspended until the flush 
record reaches the device driver's buffer. Flush records must not be 
consumed by the monitor. That is, a monitor that receives a flush 
record on a DosMonRead call, must return it to the data stream by 
calling DosMonWrite. 

Note: Refer to information for a specific character device driver in 
IBM Operating System/2 Technical Reference, Volume 1 regarding 
the type of flush support required for Its monitors. 

A data record consists of a flag word and the data itself. A flag word 
contains information meaningful to the monitors and devices whose 
data streams they are monitoring. The flag WORD is always the first 
word in the data record. The length of a data record that passes 
through a monitor chain must be less than or equal to the length of 
the device driver's monitor chain buffer minus 2 bytes. 

Note: Refer to information for a specific device driver in the IBM 
Operating System/2 Technical Reference, Volume 1 for descriptions 
of flags and data in the records passing through its monitor chains. 
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On return from DosMonRead, Bytecnt is set to the number of bytes in 
tlie recently moved data record. Since this length may not equal the 
length of the private data area, the value of Bytecnt should be 
refreshed before the monitor reissues the DosMonRead call. 

A monitor can only issue DosMonRead from an input buffer previ- 
ously registered to an opened device by the same process. That is, a 
monitor registered by one process, or application, may not 
DosMonRead data from an input buffer of a monitor registered by 
another process. 

If DosMonReg has not completed registration of a monitor's input and 
output buffers, DosMonRead returns ERROR_MONJNVALID_PARMS. 
A monitor does not have access to the device's data stream until 
DosMonReg completes successfully. 

DosMonRead issued by a monitor thread after DosMonClose is 
issued by another thread in the same process returns the error code, 
ERROR_MON_BUFFER_EMPTY. When DosMonClose is issued, the 
monitor loses access to the device's data stream. The monitor 
should stop issuing DosMonRead calls before making the 
DosMonClose call. 

Threads responsible for moving keystroke data through a monitor 
chain must pay special attention to the thread priority. Keystroke 
monitor threads must execute within the time critical priority class. 
More specifically these threads must execute at a priority level 
greater than or equal to the lowest level in the time critical priority 
class. The preferred level is level 0. This applies to any threads that 
read (DosMonRead), process or write (DosMonWrite) keystroke 
monitor data. 
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Purpose 

DosMonReg establishes an input and output buffer structure to 
monitor an I/O stream for a character device. 

Calling Sequence 

EXTRN DosMonReg: FAR 

PUSH WORD Handle 

PUSH@ OTHER Bufferl 

PUSH@ OTHER BufferO 

PUSH WORD Posflag 

PUSH WORD Index 

CALL DosMonReg 

Where 

Handle 

is the device handle returned from a previous OosMonOpen call. 
Bufferl 

is the monitor's input buffer. The monitor dispatcher moves data 
records into this buffer from the previous monitor, if any, in the 
chain or from the chain's first buffer. The monitor takes data from 
this buffer for filtering by calling DosMonRead. 

BufferO 

is the monitor's output buffer. The monitor places filtered data 
into this buffer by calling DosMonWrite. The monitor dispatcher 
moves data records from this buffer to the next monitor, if any, in 
the chain or into the device driver's monitor chain buffer, if the 
monitor is the last in the chain. 

Posflag 

Is the position preference for locating the monitor in the monitor 
chain. 

0 = no position preference 

1 = monitor placed at beginning of chain 

2 = monitor placed at end of chain. 



; Handle from DosMonOpen 
; Input buffer 
; Output buffer 
; Position flag 
; Index 
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Based on this specified position preference and on the position 
preference of those monitors from the same or different processes 
that have previously registered with the same chain, the monitor 
will be positioned within the chain as follows: 

The first monitor in a chain that registers as 1 will be placed at the 
head of the chain. The next monitor that registers as 1 will follow 
the last monitor registered as 1, and so forth. Similarly, the first 
monitor that registers as 2 will be placed at the end of the chain. 
The next monitor that registers as 2 will be placed before the last 
monitor that registered as 2, and so forth. The first monitor that 
registers as 0 will be placed before the last monitor if any, that 
registered as 2. The next monitor that registers as 0 will be 
placed before the last monitor that registered as 0 and so forth. 

Index 

is a device specific value, denoting the data stream for the device 
to be monitored. Currently, the keyboard and mouse devices 
define this in terms of the session number (from one to maximum 
session number). for keystroke and mouse monitors, indi- 
cates the session of the calling thread. Refer to OS/2 Technical 
Reference, Volume 1 for further information on how data streams 
are defined for each device. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

DosMonOpen must first be issued to establish a connection between 
the device and monitor. The monitor requires this handle to register 
the pair of buffers with the device. 

The monitor's Input and output buffers must be In the same segment. 
The first word of each buffer must contain the buffer length, length 
word inclusive, when DosMonReg is issued. The length of each 
buffer must be greater than or equal to the length of the device driv- 
er's monitor chain buffer plus 20 bytes. 
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Note: Refer to information for a specific character device driver in 
tlie IBM Operating System/2 Technical Reference, Volume 1 for spec- 
ification of the size of the device driver monitor chain buffer. 

DosMonReg formats the monitor's input and output buffers as 
needed. The format and semantics of this buffer are not visible to the 
monitor application and are subject to change. 

Until there Is successful return from the DosMonReg call no character 
will enter the monitor's input buffer. Therefore, the monitor will not 
have access to the device's data stream. It Is the application's 
responsibility to synchronize completion of DosMonReg and subse- 
quent data stream monitoring with device input Into the data stream- 
Suppose an application required that all key strokes are monitored 
including 'type-ahead' key strokes. First the application Issues 
DosMonOpen and DosMonReg to register a keystroke monitor. From 
the time the application is invoked through the time the keystroke 
monitor is registered and gains access to the data stream, the 
monitor sees no type-ahead key strokes. Since no monitor is regis- 
tered at this time, type-ahead key strokes pass directly through to the 
device driver's API buffer. So that these type-ahead key strokes are 
not lost to the monitor, the monitor empties the keyboard's API buffer 
by making repeated KbdCharIn calls before issuing its first 
DosMonRead call. Refer to the OS/2 Programmer's Guide for more 
information on this technique. 

Threads responsible for moving keystroke data through a monitor 
chain must pay special attention to the thread priority. Keystroke 
monitor threads must execute within the time critical priority class. 
More specifically these threads must execute at a priority level 
greater than or equal to the lowest level in the time critical priority 
class. The preferred level is level 0. The thread that makes the call 
to DosMonReg must also be executing in the time critical priority 
class. 
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Purpose 

DosMonWrite moves a filtered data record from the monitor's private 
data area into tfie monitor's output buffer. 

Calling Sequence 

EXTRN DosMonWrite: FAR 

PUSH© OTHER BufferO ;Monitor output buffer 

PUSH@ OTHER DataBuffer ;Buffer from which records are taken 

PUSH WORD Bytecnt ; Number of bytes 

CALL DosMonWrite 

Where 

BufferO 

is the monitor output buffer. 

DataBuffer 

is the monitor's private data area that contains a filtered data 
record of length Bytecnt. DosMonWrite moves this filtered data 
record into the monitor's output buffer. 

B/tecnf 

is the number of bytes in the data record. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

Device monitors are part of the data flow path through a device 
driver. They must respond rapidly so they do not delay I/O. This is 
especially important in the case of l(ey board monitors. 

A monitor process should be written so the threads that read and 
write the monitor data run at a high priority and so they never 
perform operations, such as I/O or semaphore waits, that might delay 
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them. The monitor process can have other threads running at normal 
priorities to handle such things. 

Each call to DosMonWrite places a single complete filtered data 
record into the data stream. The data sent by this call is considered 
to be a whole record. 

It is necessary to ensure all data is cleaned out of the data stream at 
certain times. This technique is known as flushing. A specially 
marked record or flush record, is placed into the data stream by the 
device driver and passes through all monitors in the chain to allow 
them to perform a device-specific, prescribed activity. Placement of 
new data records into the data stream is suspended until the flush 
record reaches the device driver's buffer. Flush records must not be 
consumed by the monitor. Flush records must be returned to the data 
stream by issuing DosMonWrite. 

Note: Refer to information for a specific device driver in the IBM 
Operating System/2 Technical Reference, Volume 1 regarding the 
type of flush support required for its monitors and restrictions on data 
record consumption. 

A data record is defined as a word that contains flags meaningful to 
monitors and devices whose data streams they are monitoring. The 
flag word is always the first word in the data record. A monitor can 
modify the data record received on the last DosMonRead call before 
it issues DosMonWrite to return it to the device's data stream. 
However, the monitor should not alter the order within a data record. 

Note: Refer to information for a specific device driver in the IBM 
Operating System/2 Technical Reference, Volume 1 for descriptions 
of flags and data in the records passing through its monitor chains. A 
monitor cannot write a data record into its output buffer that has a 
length greater than the length of the device driver's monitor chain 
buffer minus 2 bytes. 

A monitor can only issue DosMonWrite to an output buffer already 
registered to an opened device. DosMonWrite returns the 
ERROR_MONJNVALID_PARMS return code if the DosMonReg call 
that registered the monitor's Input and output buffers is not complete. 
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A monitor does not have access to the device's data stream until 
DosMonReg completes successfully. 

DosMonWrite issued by a monitor thread after DosMonClose is 
Issued by another thread in the same process returns the error, 
ERROR_NOT_ENOUGH_MEMORY. The monitor loses access to the 
device's data stream when DosMonClose is issued. The monitor 
should stop issuing DosMonWrite calls before making the 
DosMonClose call. 

Threads responsible for moving keystroke data through a monitor 
chain must pay special attention to the thread priority. Key- 
stroke monitor threads must execute within the time critical priority 
class. More specifically these threads must execute at a priority level 
greater than or equal to the lowest level in the time critical priority 
class. The preferred level is level 0. This applies to any threads 
that read (DosMonRead), process, or write (DosMonWrite) keystroke 
monitor data. 
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Purpose 

DosMove moves a specified fiie. 
Calling Sequence 

EXTRN DosMove: FAR 

PUSH@ ASCIIZ OldPathName :01d path name 

PUSH@ ASCIIZ NewPathName :New path name 

PUSH DWORD 0 ; Reserved (must be 0) 

CALL DosMove 

Where 

OldPathName 

is the old patli name of tlie fiie to be moved. 

NewPathName 

is tlie new patii name of tlie fiie. 

Returns 

IF AX = 0 tiien NO error 
ELSE AX = error code 

Family API Considerations 

Some options operate differently in the DOS mode than they do in the 
OS/2 mode. Therefore, the following restriction applies to DosMove 
when coding in the DOS mode: 

Files passed to OldPathName and NewPathName are truncated by 
the system in the DOS mode only. The operator must truncate ail 
files passed to OldPathName and NewPathName in the OS/2 mode or 
an error code is returned. 
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Remarks 

If a drive is used in the NewPathName string, it must be the same as 
the drive specified or implied in the OldPathName string. The direc- 
tory paths need not be the same, allowing a file to be moved to 
another directory and renamed in the process. Global filename char- 
acters are not allowed in the filename. 
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Purpose 

DosMuxSemWait blocks a current thread until one of the specified 
semaphores clear. 

Calling Sequence 

EXTRN DosMuxSemWait: FAR 

PUSH(a WORD IndexNbr ; Index number of event (returned) 

PUSH@ OTHER ListAddr ; Semaphore list 

PUSH DWORD Timeout ; Timeout 
CALL DosMuxSemWait 



Where 

IndexNbr 

is where the index number of the semaphore that satisfies the 
wait request is returned. 

ListAddr 

is a list of event descriptors that define the semaphores to be 
waited on. The list is composed of a one word count of the 
number of semaphore descriptors in the list, followed by the 
semaphore descriptors. An application can wait on up to 16 
semaphores at once. 

Semaphore list format: 

DW semcount ; Number of semaphores 
; specified in list 
N * / DW 0 ; Reserved, must be G 

\ DD ? ; Semaphore handle 

Timeout 

is the count, in milliseconds, until the requesting tasl( is to resume 
execution if none of the specified semaphores are cleared. The 
meaning of the specified values are: 

If value = -1 

DosMuxSemWait waits indefinitely for a semaphore clear. 
If value = 0 

there is an immediate return if no semaphores are clear. 
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If value > 0 

value Is the number of milliseconds to wait for a semaphore to 
clear. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

DosMuxSemWait checks a semaphore list. If any of the semaphores 
clear, DosMuxSemWait returns. If all are set, DosMuxSemWait 
blocks (until Timeout) until one of the semaphores clear. 
DosMuxSemWait returns when one of the semaphores on the list 
clears. This is known as an "edge-triggered" procedure. It is pos- 
sible for the semaphore to reset before the thread returns to the 
caller from the DosMuxSemWait call. 

Waiting threads using one of the functions DosSem Request, 
DosSemSetWait, or DosSemWalt, (known as "level-triggered" func- 
tions) may or may not resume. This decision depends on the sched- 
uler's dispatch order and the activity of other threads in the system. 
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Purpose 

DosNewSize changes the size of a file. 
Calling Sequence 

EXTRN DosNewSize: FAR 

PUSH WORD FileHandle ;F11e handle 
PUSH DWORD FileSize ; File's new size 
CALL DosNewSize 

Where 

FileHandle 

Is the handle of the file whose size is being changed. 

FileSize 

is the file's new size in bytes. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

DosNewSize can not change the size of Read/Only files. 
DosSetFlleMode (Set File Mode) must be used to change a Read/Only 
file attribute to 0, and then change the file's size. Refer to 
"DosSetFlleMode - Set File Mode" on page 2-230. 

The value of new bytes in the extended file is undefined. The file 
system attempts to allocate the riew size in a contiguous space on the 
media. 
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Purpose 

DosOpen creates or opens a specified file. 
Calling Sequence 



EXTRN 


DosOpen: FAR 




PUSH© 


ASCIIZ 


Fi 1 eName 


;File path name 


PUSH@ 


WORD 


FileHandle 


;File handle 


PUSH© 


WORD 


ActionTaken 


;Action taken 


PUSH 


DWORD 


FileSize 


;File primary allocation 


PUSH 


WORD 


Fi 1 eAttri bute 


;File Attribute 


PUSH 


WORD 


OpenFI ag 


;Open function type 


PUSH 


WORD 


OpenMode 


;Open mode of the file 


PUSH 


DWORD 


0 


: Reserved (must be 0) 


CALL 


DosOpen 







Where 

FlleName 

is tlie path name of tlie file to be opened. 

FileHandle 

is where the system returns the file handle. 

ActionTaken 

is where the system returns a description of the action taken as a 
result of DosOpen. 

0001 H = file exists 
0002H = file created 
0003H = file replaced. 

FlleSize 

is the file's new size in bytes. 

FileAttrlbute 

File attribute bits are defined as follows: 

0001 H = read only file 
0002H = hidden file 
0004H = system file 
001 OH = subdirectory 
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0020H 
0040H 
0080H 
0100H 
0200H 
0400H 
0800H 
1000H 
2000H 
4000H 
8000H 



file archive 

Reserved 

Reserved 

Reserved 

Reserved 

Reserved 

Reserved 

Reserved 

Reserved 

Reserved 

Reserved 



These bits may be set individually or in combination. For 
example, an attribute of 0021H Indicates a read-only file which 
should be archived. 

OpenFlag 

specifies the action to take If the file exists. 



OpenFlag specification: 
Low Order Byte 

xxxx action taken if file exists 

0000 fail 

0001 open file 

0010 replace file 

xxxx action taken if file doesn't exist 

0000 fail 

0001 create file 



High Order Byte 
• 00000000 'B 



reserved and set to 0 



OpenMode 

is an open mode that consists of the following bit fields: 

• DASD Open flag 

• Inheritance flag 

• Write - through flag 

• Fail — errors flag 
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• Sharing mode field 

• Access field 

• Reserved bit fields 

Open Mode Bits - tiie bit field mapping is sliown as follows: 

Open Mode 5432109876543210 
bits DWFRRRRRISSSRAAA 

D - DASD Open 

The file is opened as follows: 

If D = 0 FileName represents a file to be opened in the normal 
way. 

If D = 1 FileName is "Drive:" and represents a mounted disl< or 
diskette volume to be opened for direct access. 

W - File Write-through 

The file is opened as follows: 

If W = 0 Writes to the file may be run through the DOS buffer 
cache. 

If W = 1 Writes to the file may go through the DOS buffer cache 
but the sectors are written (actual file I/O completed) 
before a synchronous write call returns. This state of the 
file defines it as a synchronous file. 

/ - Inheritance Flag 

If I = 0 File handle Is inherited by a spawned process resulting 
from a DosExecPgm call. 

If I = 1 File handle is private to the current process. 

This bit is not inherited by child processes. 

F - Fail-Errors 

Media I/O errors are handled as follows: 

If F = 0 Reported through the system critical error handler. 

If F = 1 Reported directly to the caller via return code. 

This bit is not inherited by child processes. Media I/O 
errors generated through an lOCtI category eight function 
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always get reported directly to the caller via return code. 
The Fail-Errors function applies only to non-IOCtI 
handle-based type file I/O calls. 

R Reserved and must be 0 field. 

S - Sharing Mode 

The file sharing mode field defines what operations other proc- 
esses may perform on the file. 

If S = 001 Deny Read/Write access 

If S = 010 Deny Write access 

If S = 01 1 Deny Read access 

If S = 100 Deny neither Read or Write access (Deny None) 
Any other value is invalid. 

A - Access Mode 

The file access is assigned as follows: 

If A = 000 Read/Only access 
If A = 001 Write/Only access 
If A = 010 Read/Write access 

Any other combinations are invalid. When opening a file, inform OS/2 
what operations other processes can perform on this file (sharing 
mode). If it is permissible for other processes to continue to read this 
file while the process is operating, specify Deny Write. 

If a read/write file is opened with read/write access, an open request 
from another process will fail unless both processes use sharing 
mode Deny None. However, if the file Is read-only and the file is 
opened with read-only access, an open request from another process 
will fail unless both processes used sharing modes of Deny None or 
Deny Write. 
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Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Family API Considerations 

Some options operate differently in the DOS mode than they do in the 
OS/2 mode. Therefore, the following restrictions apply to DosOpen 
when coding in the DOS mode: 

• Inheritance Flag is not supported. 

• WriteThroughFlag must be set to 0. 

• FailErrorsFlag must be set to 0. 

• Share Mode has meaning only If SHARE Is loaded, Ignored if 
SHARE is not loaded. 

• Access field has meaning only if SHARE is loaded, ignored if 
SHARE Is not loaded. 

• Access mode has meaning only If SHARE is loaded, ignored If 
SHARE is not loaded. 

• FlleName files passed to DosOpen must be truncated by the oper- 
ator or an error code is returned. In the OS/2 mode, the system 
does the truncation. 

When a read/only file is created it is always opened In compatibility 
mode, and is given read/write access. 

Remarks 

The read/write pointer is set at the first byte of a file. Issue 
DosChgFiiePtr to change the read/write pointer. 

The following example illustrates how DosScanEnv and 
DosSearchPath could be used to provide DosOpen with path 
searching: 

Let DPATH be an environment variable in the environment segment 
of the process. 

"DPATH=c:\sysdir;c:\init" /* in tlie 
environment */ 
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The following two code fragments are equivalent: 
DosScanEnvC'DPATH", &PathRef); 

DosSearchPath(0, /* Path Source Bit = O */ 

PathRef, "myprog.ini", &ResultBuffer, 
ResultBufLen): 

DosOpen (ResultBuffer, ... ); 

DosSearchPath(2, /* Path Source Bit = 1 */ 

"DPATH", "myprog.ini", &ResultBuffer, 
ResultBufLen); 

DosOpen (ResultBuffer, ... ); 

Issue DosQFIIelnfo to obtain the file's date and time. Issue 
DosSetFilelnfo to set date and time, its attribute can be obtained 
through DosQFileMode. 

The FileSize parameter affects the size of the file only when it is 
created or replaced. If an existing file is opened, FileSize is ignored. 

The DASD Open bit parameter is the Direct I/O flag. It providesi an 
access mechanism to a disk or diskette volume independent of the 
file system. This mode should only be used by systems programs 
and not by application programs. This mode of opening the currently 
mounted volume on the drive is used to return a handle to the caller 
that represents the logical volume as a single file. To block other 
processes from accessing the logical volume, the caller must issue 
DosDevlOCtI Category 8, sub-function 0 which requires the file handle 
for the logical volume returned by DosOpen. 

DosOpen and DosSetFHandState can set the file handle state bits. An 
application can issue DosQFHandState to query the file handle state 
bits and the Open Mode field. Use the returned file handle for subse- 
quent input and output to the file. The value of new bytes in the 
extended file is undefined. 

When a critical error occurs that the application cannot handle, it 
must reset critical error handling to be done by the system. Issue 
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DosSetFHandState and reissue the I/O to accomplish this. The 
expected critical error reoccurs and is passed to the system critical 
error handler. The instant in time at which the effect of the DosOpen 
is visible at the application level it is unpredictable when asynchro- 
nous I/O is pending. This is the recommended action to take and is 
not done automatically. 

Notes: 

• DosOpen opens any normal or hidden file whose name matches 
the name specified. 

• A multitasking system must be able to use semaphores to create 
and manage files. DosOpen may be used as a test and set 
semaphore when used to create a new file. 

• When a file is closed, any sharing restrictions placed on it by the 
open are canceled. 

• The file system attempts to allocate the new size in a contiguous 
space on the media. 

• FileAttribute can not be set to Volume Label. Volume labels can 
not be opened. 

• To set the file read/only attribute issue DosSetPileMode or the 
OS/2 ATTRIB command. 

• If the file is inherited by a spawned process, all sharing and 
access restrictions are also inherited. 

• If an open file handle is duplicated by DosDupHandle, all sharing 
and access restrictions are also duplicated. 

Sharing Modes 

• Deny Read/Write Mode (Exclusive) 

If a file is successfully opened in Deny Read/Write mode, access 
to the file is exclusive. A file currently open in this mode cannot 
be opened again in any sharing mode by any process until the file 
is closed. 

• Deny Write Mode 

A file successfully opened in Deny Write sharing mode, prevents 
any other write access opens to the file (A = 001 or 010) until the 
file is closed. An attempt to open a file in Deny Write mode is 
unsuccessful if the file is currently open with a write access. 
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• Deny Read Mode 

A file successfully opened in Deny Read sharing mode, prevents 
any other read sharing access opens to the file (A = 000 or 010) 
until the file Is closed. An attempt to open a file in Deny Read 
sharing mode Is unsuccessful if the file is currently open with a 
read access. 

• Deny None Mode 

A file successfully opened in Deny None mode, places no 
restrictions on the read/write accessibility of the file. 
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Purpose 

DosOpenQueue opens a queue for the current process. 
Calling Sequence 

EXTRN DosOpenQueue: FAR 

PUSH@ WORD OwnerPID ;Queue owners' RID 

PUSH@ WORD QueueHandle ; Handle of queue 

PUSH@ ASCIIZ QueueName ; Queue name string 

CALL DosOpenQueue 

Where 
OwnerPID 

is where the process ID of the queue owner is returned. 

QueueHandle 

is where the write handle of the queue is returned. 

QueueName 

is the name of the queue provided by a previous DosCreateQueue 
call. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

Before elements can be sent to a queue, the queue must be opened. 
DosCreateQueue opens the queue for that process. 

When specifying the name for the queue, the ASCIIZ name string pro- 
' vided must include the prefix \QUEUES\ The process that issues the 
DosCreateQueue does not have to do a DosOpenQueue. 
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Purpose 

DosOpenSem opens a system semaphore. 
Calling Sequence 

EXTRN DosOpenSem: FAR 

PUSH@ DWORD SemHandle -.Semaphore handle (returned) 

PUSH@ ASCIIZ SemName ; Semaphore name string 

CALL DosOpenSem 

Where 
SemHandle 

is where the handle of the system semaphore created by 
DosCreateSem is returned. This handle must be supplied by any 
requests directed to the same semaphore. 

SemName 

is the name of the system semaphore which was created using 
DosCreateSem. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

DosCreateSem must create the semaphore before DosOpenSem can 
open it. DosOpenSem only returns the handle of the semaphore, it 
does not test or change the value of the semaphore. 

If a process with open semaphores issues a DosExecPgm, the new 
process inherits any open semaphore handles. Ail inherited 
semaphores are initially not owned by the child process, even if the 
parent owned them at the time of the Exec. (Only one process can 
own a semaphore at a time.) 
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Note: Under OS/2, system semaphores reside in a memory buffer 
rather than on a disk file. This means that when the last process 
which has a semaphore open (via DosCreateSem or DosOpenSem) 
exits, the semaphore disappears and must be recreated by its next 
user. 
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Purpose 

DosPeekQueue retrieves an element from a queue without removing 
It from the queue. 



Calling Sequence 




EXTRN 


DosPeekQueue: FAR 




PUSH 


WORD 


QueueHandle 


Handle of queue to read from 


PUSH® 


DWORD 


Request 


Request identification data 








(returned) 


PUSH? 


WORD 


DataLength 


Length of element received 








(returned) 


PUSH? 


DWORD 


DataAddress 


Address of element received 








(returned) 


PUSH@ 


WORD 


El ementCode 


Indicator of element received 








(returned) 


PUSH 


WORD 


NoWait 


Indicate no wait if queue empty 


PUSH@ 


WORD 


El emPri ori ty 


Priority of element (returned) 


PUSH 


DWORD 


SemaphoreHandle 


Semaphore Handle 


CALL 


DosPeekQueue 





Where 

QueueHandle 

is the handle of the queue from which to obtain an element. 
Request 

is filled in with the following information: 

The first word is the PID of the process which added the element 
to the queue. 

The second word is used for event coding by the application. The 
data in this word is the same as that furnished by the Request 
parameter on the DosWriteQueue request for the corresponding 
queue element. The value of this data is understood by the client 
thread and by the server thread. There is no special meaning to 
this data and the operating system does not alter the data. 

DataLength 

is where the length of the received data is returned. 
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DataAddress 

is where the element being retrieved from the queue is returned. 
ElementCode 

indicates to start at the beginning of the queue or at a particular 
element. This field Is set to: 

0 by the application 

to Indicate start at the beginning of the queue 
Non-0 by the DosPeel^Queue function 

to Indicate the element returned, or by the owner to Indicate 

"get next element." 

NoWait 

specifies the action to be performed when there are no entries on 
the queue. 

If value = 0 

the requesting thread waits. 
If value = 1 

the requesting thread does not wait. 

ElemPriority 

is the priority specified when the element is added to the queue. 
This is a numeric value In the range of zero to 15, with 15 being 
the highest priority. 

SemaphoreHandle 

is the handle of a semaphore which is to be cleared when the 
queue has data placed into it and NoWait = 1 is specified. The 
semaphore may be either a RAM or systenri semaphore. 

If this handle Is for a RAM semaphore, that semaphore must be in 
a segment shared between the queue owner's process and any 
process that issues a DosWriteQueue request to an associated 
queue. 

if multiple threads are processing elements from the queue using 
a NoWait value = 1, the same semaphore must be provided on all 
DosPeeicQueue or DosReadQueue requests. 
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Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

DosPeekQueue retrieves elements from a specified queue without 
removing that element from the queue. If the queue is empty, and 
wait is specified, the thread is placed in a wait state waiting for an 
element to be added to the queue. If the NoWait option is selected, 
the request does not place the thread in a wait state, but returns with 
a code indicating there are no entries on the queue. 

ElementCode Is an Indicator of the element to peek or read next. Fol- 
lowing a peek request, ElementCode contains an identifier of the 
element which has been peeked The next DosPeekQueue which pro- 
vides this identifier as the ElementCode parameter, returns the next 
element following the element Indicated by ElementCode. A subse- 
quent DosReadQueue request that provides this identifier reads the 
Indicated element. 

When the application program sets this field to 0, the next 
DosPeekQueue or DosReadQueue request accesses the first element 
in the queue. 

Only the queue owner (the process which created the queue via 
DosCreateQueue) is allowed to issue this call. Any thread within that 
process may also Issue DosPeekQueue calls to any queue owned by 
that process. 

The semaphore provided by SemaphoreHandle would typically be 
used with a DosMuxSemWait request to wait on a queue or any of 
several other events. This operand is Ignored If NoWalt = 0 Is speci- 
fied. 
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Purpose 

DosPFSActivate specifies the code page and font to mal<e active for 
the specified printer and Process ID. 

Calling Sequence 

EXTRN DosPFSActivate: FAR 

PUSH WORD Spl Handle ;Temporary Spool File handle 

PUSH© DWORD BytesWritten ; Number of bytes written (returned) 

PUSH© ASCIIZ PrinterName ; Printer name string 

PUSH WORD CodePage :Code Page to malce active 

PUSH WORD FontID ;Font ID to malce active 

PUSH WORD Process ID ;ProcessID 

PUSH DWORD Reserved ; Reserved, set to 0 

CALL DosPFSActivate 



Where 

SptHandle 

is the fiie handle of the temporary spool file for which code page 
and font switching is being activated. 

BytesWritten 

is where the number of bytes written to the temporary spool file 
are returned. 

PrinterName 

is the name of the printer for which code page and font switching 
is being activated. 

CodePage 

specifies the code page to make active for the specified printer 
and process id. 

FontID 

specifies the font within the specified code page to mal<e active for 
the specified printer and process id. 

For download fonts, the FontID is that specified in the printer font 
file. 
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For cartridge fonts, the FontID is tlie number specified on tlie label 
of the cartridge and in the DEVINFO statement for the printer. 

A value of 0 (OOOOh) for both the CodePage and FontId indicates 
that the hardware default code page and font should be made 
active. 

A value of 0 for the font ID but not the code page indicates that any 
font ID is acceptable for the code pages. 

ProcessID 

specifies the process ID of the requester. 

Reserved 

Is reserved and set equal to zero. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

For a description of the return values for DosPFSActivate, see the 
Remarks section below: 

Remarks 

DosPFSActivate is intended for use only by applications that replace 
the spooler as a print monitor and that do code page switching. 
Other applications should use printer lOCtIs to manipulate printer 
code page switching. 

DosPFSActivate is located in SPOOLCP.DLL (not in DOSCALLS.LIB) 
and requires an import statement in the module definition file. See 
the IBM Operating System/2 Programmer's Guide, Module Definition 
File Statements section for Information regarding the Import state- 
ment. 
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Return values are: 




Msanino 

mWm wWaalls* 


2 


Code page not available 


4 


Font ID not available 


9 


Code page switcher Internal error 


10 


Invalid printer name as input 


13 


Received code page recjuest when code page switcher not 




initialized 


15 


PID table full. Cannot activate another entry 


19 


I/O error reading font file control sequence section 


21 


I/O error reading font file font definition block 


23 


I/O error while writing to temporary spool file 


24 


Disk full error while writing to temporary spool file 


25 


Bad spool file handle 
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Purpose 

DosPFSCIoseUser indicates to the Font Switcher that the specified 
process has closed its spool file. The Font Switcher may then free 
any resources being used to track code page and font switching for a 
process. 

Calling Sequence 

EXTRN DosPFSCIoseUser: FAR 

PUSH© ASCIIZ PrinterName ;Printer name string 

PUSH WORD ProcessID ;ProcessID 

PUSH DWORD Reserved ; Reserved, set to 0 

CALL DosPFSCIoseUser 

Where 

PrinterName 

is the name of the printer for which code page and font switching 
is being closed. 

ProcessID 

specifies the process ID of the requester. 

Reserved 

is reserved and set equal to 0. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

DosPFS Activate is intended for use only by applications that replace 
the spooler as a print monitor and that do code page switching. 
Other applications should use printer lOCtIs to manipulate printer 
code page switching. 
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DosPFSActivate is located in SPOOLCP.DLL (not in DOSCALLS.LIB) 
and requires an import statement in the module definition file. Refer 
to the IBM Operating System/2 Programmer's Guide, Module Defi- 
nition File Statements section for information regarding the import 
statement. 

Return values are: 
Value Meaning 

8 Attempted to close process ID not active 

9 Code page switcher internal error 

10 Invalid printer name as input 

13 Received code page request when code page switcher not 
initialized 
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Purpose 

DosPFSInit allows the Font Switcher to initialize code page and font 
switching for a specified printer. 



Calling Sequence 

EXTRN DosPFSInit: FAR 



PUSH@ 


OTHER 


CPHdw 


;Hdw Font definition list 


PUSH@ 


ASCIIZ 


FontFileName 


;File pathname of the 








;font file to be used 


PUSH© 


ASCIIZ 


PrinterType 


; Printer type string 


PUSH© 


ASCIIZ 


Pri nterName 


; Printer name string 


PUSH 


WORD 


Instances 


; Number of spool instances 


PUSH 


DWORD 


Reserved 


; Reserved 


CALL 


DosPFSInit 





Where 
CPHdw 

points to a list in the following fornnat which specifies the Hard- 
ware code page and fonts the printer is equipped with: 

WordO 

Number of definitions which follow 
DWord 1 / n 

Code page number (1st Word of DWord) and Font ID (2nd 
Word of DWord) for each hardware font in order corre- 
sponding to the hardware code page and font selection 
numbers (i.e. the first code page and font ID value corre- 
sponds to the default hardware font 0, second value corre- 
sponds to hardware font 1, third to hardware font 2, etc.. If 
the default hardware font is not known, 0 should be specified 
for the default code page and font). 

FontFileName 

is the pathname of the font file of the specified printer for which 
code page and font switching is being initialized. 
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PrintBrType 

is the printer type ID. 

PrinterName 

is the name of the printer for which code page and font switching 
is being initialized. 

Instances 

Is the maximum number of different Instances of use for which 
code page and font switching should be tracked. This value is 
advisory for the Font Switcher to be able to allocate enough 
resources for the specified number of instances to be tracked. 

Reserved 

is reserved and set equal to 0. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

DosPFSInit is intended for use only by applications that replace the 
spooler as a print monitor and that do code page switching. Other 
applications should use printer lOCtis to manipulate printer code 
page switching. 

DosPFSInit is located in SPOOLCP.DLL (not DOSCALLS.LIB) and 
requires an import statement in the module definition file. Refer to 
the IBM Operating System/2 Programmer's Guide, Module Definition 
File Statements section for information regarding the import state- 
ment. 
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Return values are: 
Value Meaning 

I Code page switcher already Initialized. 

3 User entered too many ROMs in DEVINFO. Initialization 

continued with the rest. 
6 Wrong or missing font file ID. 

9 Code page switcher internal error. 

10 Invalid printer name as input. 

I I Printer type input does not match that in font file. 
12 Could not get storage for control blocks. 

14 Could not open font file during initialization. 
17 Switcher reports too many PID entries. 

19 I/O error reading font file control sequence section. 

20 I/O error reading font file header. 

21 I/O error reading font file font definition block. 

22 Some fonts bad due to error in font file, initialization con- 
tinued 
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Purpose 

DosPFSQueryAct queries the active code page and font for the speci- 
fied printer and Process ID. 



Calling Sequence 

EXTRN DosPFSQueryAct: FAR 

PUSH© ASCIIZ PrinterName 

PUSH@ WORD CodePage 

PUSH@ WORD Fontid 

PUSH WORD ProcessID 

PUSH DWORD Reserved 

CALL DosPFSQueryAct 



; Printer name string 
;Code Page return 
;Font ID return 
; Process ID 
; Reserved, set to 0 



Where 

PrinterName 

is the name of the printer for which the active code page and font 
is being queried. 

CodePage 

is where the currently active code page for the specified printer 
and process ID are returned. 

Fontid 

is where the currently active Font ID number for the specified 
printer and process ID are returned. 

ProcessID 

specifies the process ID of the requester. 
Reserved 

Is reserved and set equal to 0. is reserved for future use. 



Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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Remarks 

DosPFSQueryAct is intended for use only by applications that replace 
the spooler as a print monitor and that do code page switching. 
Other applications should use printer lOCtIs to manipulate printer 
code page switching. 

DosPFSQueryAct is located in SPOOLCP.DLL (not in DOSCALLS.LIB) 
and requires an import statement in the module definition file. Refer 
to the IBM Operating System/2 Programmer's Guide, Module Defi- 
nition File Statements section for Information regarding the import 
statement. 

Return values are: 
Value Meaning 

9 Code page switcher internal error. 

10 Invalid printer name as input. 

13 Received code page request when code page switcher not 
initialized. 

16 Received request for process ID not In the PID table. 
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Purpose 

DosPFSVerifyFont indicates wliether the specified code page and font 
within that code page are available in the font file for the specified 
printer. 

Calling Sequence 

EXTRN DosPFSVeri fyFont : FAR 

PUSH@ ASCIIZ PrinterName 

PUSH WORD CodePage 

PUSH WORD Fontid 

PUSH DWORD Reserved 

CALL DosPFSVerifyFont 

Where 

PrinterName 

is the name of the printer for which the code page and font 
switching setup is being queried. 

CodePage 

is the code page to validate. Values may be 0 to 65535. 
FonUd 

is the Font ID to validate. Values may be 0 to 65535. A value of 0 
indicates that any font within the specified code page is accept- 
able. 

Reserved 

is reserved and set equal to 0. 

Returns 

IF AX = 0 then NO error 
' ELSE AX = error code 



; Printer name string 
;Code Page to validate 
:Font Id to validate 
; Reserved, set to 0 
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Remarks 

DosPFSVerifyFont is intended for use oniy by applications that 
replace the spooler as a print nrtonitor and that do code page 
switching. Other applications should use printer iOCtIs to manipulate 
printer code page switching. 

DosPFSVerifyFont is located in SPOOLCP.DLL (not in 
DOSCALLS.LIB;) and requires an import statement in the module 
definition file. Refer to the IBM Operating System/2 Programmer's 
Guide, Module Definition File Statements section for information 
about the import statement. 

Return values are: 

Value Meaning 

2 Code page not available 

4 Font ID not available 

10 Invalid printer name as Input. 

13 Received code page request when code page switcher not 
initialized. 
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Purpose 

DosPhysicalDisk obtains information on partitionable 6\sks. 
Calling Sequence 

EXTRN DosPhysicalDisk: FAR 

PUSH WORD Function 

PUSH© OTHER DataPtr 

PUSH WORD DataLen 

PUSH@ OTHER ParmPtr 

PUSH WORD ParmLen 

CALL DosPhysicalDisk 

Where 

Function 

identifies tlie type of information on the partitionabie disl((s) to 
obtain. 

The functions currently supported are: 

1 = obtain total number of partitionable disks 

2 = obtain a handle to use with Category 9 lOCtIs 

3 = release a handle for a partitionable disk 

DataPtr 

indicates the location of a buffer in which the returned information 
is placed. 

DataLen 

specifies the length of the data buffer. 

The output data for each function is described below. Note that all 
lengths are in bytes. 



;Type of information 

; Pointer to return buffer 

; Return buffer length 

; Pointer to user-supplied 

; information 

; Length of user-supplied 

; information 
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Function DataLen Returned Information 



1 2 Total number of partitionable disks in the 

system, 1 -based 

2 2 Handle for the specified partitionable disk for 

the Category 9 lOCtIs 

3 0 None - Pointer must be 0. 



ParmPtr 

indicates the location of a buffer used for input parameters. 
ParmLen 

specifies the length of the parameter buffer. 

The input parameters required for each function are described 
below. Note that all lengths are in bytes. 

Function ParmLen input Parameters 



1 0 None / must be set to 0 

2 string ASCIIZ string that 

length specifies the partitionable disk 

3 2 Handle obtained from Function 2 



Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

The ASCIIZ string used to specify the partitionable disk must be of the 
following format: 
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number : <null byte> 

where 

number specifies the partitionable 

disk (1-based) number in 
ASCII 

: must be present 

>nun byte> the byte of 0 for the 
ASCIIZ string 

The handle returned for the specified partitionable disk can only be 
used with the DosDevlOCtI call for the Category 9 Generic lOCtl. Use 
of the handle for a physical partitionable disk is not permitted for 
handle-based file system function calls, such as DosRead or 
DosClose. 
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Purpose 

DosPortAccess requests or releases access to ports for I/O privilege. 
Calling Sequence 

EXTRN DosPortAccess: FAR 

PUSH WORD Reserved 

PUSH WORD TypeOf Access 

PUSH WORD FirstPort 

PUSH WORD LastPort 

CALL DosPortAccess 

Where 

Reserved 

must be set to 0. 

TypeOfAccess 

Indicates a request for or release of access to a port. 

0 = request access 

1 = release access 

FirstPort 

specifies either the starting (low-end) number in a contiguous 
range or a single port. 

LastPort 

specifies either the ending (high-end) number in a contiguous 
range or a single port. If only one port is being used FirstPort 
needs to be set to this port number and LastPort needs to be set to 
this port. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 



;0 

; Request or release 
; First port number 
;Last port number 
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Remarks 

Note that CLI/STI privilege is also granted automatically, there is no 
need to make an additional call to DosCLI Access. 

Applications that perform I/O to port(s) in lOPL segments must 
request port access from the operating system. 

An application with no lOPL segments that accesses a device through 
a device driver or by an interface package such as VIO, will not need 
to gain port access: the device driver or interface package will be 
responsible for obtaining the necessary I/O access. 
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Purpose 

DosPtrace provides an interface into the OS/2 kerne\ to facilitate 
program debugging. 

Calling Sequence 

EXTRN DosPtrace: FAR 

PUSH© OTHER PtraceB ;Ptrace buffer (returned) 
CALL DosPtrace 

Where 
PtraceB 

is tfie Ptrace command/data buffer. This buffer is used to commu- 
nicate between the debug program and the DosPtrace routines. 

Returns 

AX = 0 

Remarks 

DosPtrace allows a parent process to control the execution of another 
process. Its Intended use Is directed toward the Implementation of 
breakpoint debugging using a debugger. The program under test 
and, the program being debugged, must be executing in OS/2 mode. 

To debug a process with multiple threads, DosPtrace allows the 
debugger to selectively suspend and resume the threads of a 
program being debugged. It also reads the registers of its individual 
threads. 

A debug program must be able to read and write the instructions, 
data, and registers of the program being debugged to insert break- 
point instructions. When a process runs in OS/2 mode, one process 
cannot directly manipulate the address space of another process. 
OS/2 controls this address space through the use of the trace flag 
facility in DosExecPgm and the Ptrace buffer in DosPtrace. 
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The steps to program debugging in a OS/2 mode follow: 

1. The debug program issues DosExecPgm for the program to be 
debugged, and specifies the trace option. 

2. The debug program calls DosPtrace with the TRC_C_Stop 
command to initialize the Ptrace Buffer. 

3. The debug program sets up a Ptrace buffer with commands for 
inserting the breakpoints, and issues repeated DosPtrace 
requests as necessary. 

4. The debug program sets up a Ptrace buffer with a command to 
begin execution and issues DosPtrace. This may be a 
TRC_C_SStep, or TRC_C_Go. 

5. When the kernel DosPtrace program receives control from the 
program being debugged, it returns to the debug program with 
the Ptrace buffer set to the current register contents and with Indi- 
cators of the reason for return. 

6. The kernel DosPtrace program receives control at a breakpoint 
interrupt, at processor exceptions, or when the program ends. 

To debug a process with multiple threads, set a field In the Ptrace 
buffer (Ptrace_B.TID) to the thread ID of the thread of interest. This 
causes the read/write register commands to receive only the register 
set of the specified thread. 

Note: For a process with multiple threads, the address space is the 
same for all the threads in the process. When commands are issued 
to read/write memory locations or set breakpoints it affects all the 
threads in the process even though the command was issued with a 
specific thread ID. 

The debugger may suspend and resume specific threads through use 
of the TRC_C_Freeze and TRC_C_Resume commands. Having only 
selected threads be affected by the breakpoints is useful for manipu- 
lating them while other threads are suspended. 

When a process debugger terminates, the program being debugged 
I also terminates. To accomplish this, an Internal link between the 
debugger and the program being debugged is maintained. This link 
is established as a result of the first successful TRC_C_Stop 
command. Once established, this link can not be reset. 
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The program being debugged does not need to be a direct cliild. As a 
result, a small window of time between the DosExecPgm call and the 
first DosPtrace call, where if the debugger terminates, the program 
being debugged cannot be cleaned up. The system terminates the 
program being debugged in a few minutes. 

Contents of the Ptrace Buffer: 



Ptrace B 






Structure 


PID 


DW 


0 


; Process ID of the process being 
debugged 


TID 


DW 


0 


; Thread ID of the process being 


Cmd 


DW 


0 


' Reauest to DosPtrace or DosPtrace 
result code 


Value 


DW 


? 


; Data to DosPtrace, or DosPtrace error 
code 


OffV 


DW 


7 


; Offset value 


SegV 


DW 


7 


; Segment value 


MTE 


DW 


7 


; Library Module handle 


rAX 


DW 


7 


; Registers AX thru SS 


rBX 


DW 


7 




rCX 


DW 


7 




rDX 


DW 


7 




rSI 


DW 


7 




rDI 


DW 


7 




rBP 


DW 


7 
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Ptrace B 






Structure 


rDS 


DW 


? 




rES 


DW 


? 




rIP 


DW 


r\ 




rCS 


DW 


? 




rF 


DW 


? 




rSP 


DW 


? 




rSS 


DW 


? 




Ptrace_B 
ENDS 









DosPtrace Commands: 

PTrace_B.Cmd must contain one of the following commands upon 
entrance to DosPTrace: 



TRC_C_Null 


EQU 
0 




Invalid 


TRC_C_ReadMemJ 


EQU 
1 






TRC_C_ReadMem_D 


EQU 
2 






TRC_C_ReadMem 


EQU 


TRC_C_ReadMem_l 




TRC_C_ReadReg 


EQU 

3 






TRC_C_WriteMemJ 


EQU 
4 
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1 no_L»_vvrueivi©iTi_u 


5 






1 nu_o_vvriieMem 




TDO O lAlrUAlkilAm i 

1 nu_u_vvriieMeiTi_i 




1 nL»_u_wriTeneg 


6 






I riU_U_ciO 


7 






1 ri>-'_v-'_ 1 6rm 


8 






1 nU_U_Ov>Tep 


tVilU 

9 






1 r\o_v<»_oiop 


10 




■ Ini 

, ini- 
tialize 


1 nu_u_rreeze 


11 






1 nL»_o_nesurne 


12 






1 r\L»_v-»_iNum 1 ooei 


COI 1 

13 






1 nVi/_\-/_vjieirr neys 


cni 1 
14 






TRC_C_SetFPRegs 


EQU 
15 






TRC_C_GetLi bName 


EQU 
16 







Commands and Required Input 

A command is issued by placing the command number in 
Ptrace_B-Cmd, and other required information into a Ptrace 
buffer, and calling DosPtrace with that buffer. 
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All of the commands require that Ptrace_B.PID be the PID of the 
process to debug. 

TRC_C_Null : Not a valid command 

Memory Operations: 

For the following commands, SegV:OffV is the affected location, 

and Ptrace_B. Value contains the value to write to or that was read 

from the debugger's memory. 

TRC_C_ReadMemJ : Read instruction 

TRC_C_ReadMem_D : Read data 

TRC_C_ReadMem : Read any memory 

TRC_C_WriteMem_l : Write instruction 

TRC_C_WriteMem_D : Write data 

TRC_C_WriteMem : Write to any memory 
Register I Thread Operations: 

For the following commands, Ptrace_B.TID must contain the 

thread ID of the thread in question. 

TRC_C_ReadReg : Examine thread's registers 

TRC_C_WriteReg : Write thread's registers 

TRC_C_Freeze : Suspend a thread 

TRC_C_Resume : Resume a suspended thread 

Command Operations: 

For the following commands, the Ptrace_B.PID must be valid. The 

Ptrace_B registers are ignored for these commands. For 

TRC_C_Go and TRC_C_SStep, any thread may gain control first. 

The TRC_C_Term command terminates the program being 

debugged. 

TRC_C_Go : Run debuggee 

TRC_C_Term : Terminate debuggee 
TRC_C_SStep : Run one instruction 
TRC_C_Stop : Initialize PTrace buffer 

Library Support: 

For TRC_C_NumToSel, Ptrace_B. Value should be set to the 
segment number on entrance, and a valid selector on exit. Also, 
Ptrace_B.MTE should be set to the module's handle. The MTE 
identifies the different library files in the program being debugged. 

For TRC_C_GetLibName, SegV:OffV should point to a buffer where 
the name of the library will be returned. PTrace_B.Value should 
hold the library's module handle (MTE). 
TRC_C_NumToSel : Convert Segment number to selector 
TRC_C_GetLibName : Return name of module 
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Floating Point Support: 

For the following two commands, SegV.OffV must contain a 
pointer to a 94 byte buffer to be used to read/write the floating 
point registers from/to. 

The layout of this area is described in the NPX287 manual under 
the heading FSAVE/FRSTOR memory layout. 
TRC_C_GetFPRegs : Read floating point regs. 
TRC_C_SetFPRegs : Write floating point regs. 
DosPtrace Return Codes: 

When DosPtrace returns to the debug program, the result is 
placed in Ptrace_B.Cmd, and reflects the reason for the return. 

The values returned are: 



TRC_C_SUC_ret 


EQUO 


; Success 


TRC_C_ERR_ret 


EQU -1 


; Error 


TRC_C_SIG_ret 


EQU-2 


; Signal 


TRC_C_TBT_ret 


EQU -3 


; Single Step 


TRC_CB_PT_ret 


EQU -4 


; Breaf(point 


TRC_C_NMI_ret 


EQU -5 


; Parity Error 


TRC_C_KIL_ret 


EQU -6 


; Process dying 


TRC_C_GPF_ret 


EQU -7 


; GP fault 


TRC_C_LIB_ret 


EQU -8 


; Library load 
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TRC C FPE ret 



EQU-9 



; FP error 



If Ptrace_B.Cmd is returned as TRC_C_ERR_ret, Ptrace_B .Value 
Is set to one of the following: 
TRACE_BAD_COMMAND EQU 1 

TRACE_CHILD_NOT_FOUND EQU 2 

TRACE_CHILD_UNTRACEABLE EQU 5 

If Ptrace_B.Cmd is returned as TRC_C_SIG_ret, the process is 
about to receive a signal. 

If Ptrace_B.Cmd is returned as TRC_C_KIL_ret, the process is 
about terminate. 

If Ptrace_B.Cmd returns as TRC_C_GPF_ret, the process creates a 
General Protection fault. The fault type is returned in 
PTrace_B. Value, and SegV:OffV contains the reference that gener- 
ated the fault. 

If Ptrace_B.Cmd Is returned as TRC_C_LIB_ret, a library module 
has been loaded. The new module table entry (MTE) is returned 
in Ptrace_B.Value. This can be used with the library support com- 
mands to identify the library module. The program module's MTE 
is returned In PTrace_B.MTE. In this case, the initial TRC_C_Stop 
command should be re-issued until TRC_C_SUC_ret is returned. 

If Ptrace_B.Cmd is returned as TRC_C_FPE_ret, the process has 
generated a floating point error. 
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Purpose 

DosPurgeQueue purges a queue of all elements. 
Calling Sequence 

EXTRN DosPurgeQueue : FAR 

PUSH WORD QueueHandle ; Handle of queue to purge 
CALL DosPurgeQueue 

Where 

QueueHandle 

is the handle of the queue to purge. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

Only the queue owner (the process which created the queue via 
DosCreateQueue) Is allowed to issue this call. Any thread within that 
process can Issue DosPurgeQueue calls to any queue owned by that 
process. 
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Purpose 

DosPutMessage outputs the message in a buffer passed by a caller to 
the specified handle. The function formats the buffer to prevent 
words from wrapping if displayed to a screen. 

Calling Sequence 

EXTRN DosPutMessage: FAR 

PUSH WORD FileHandle ; Handle of output file/device 

PUSH WORD MessageLength ; Length of message buffer 

PUSH© OTHER MessageBuffer ;Message buffer 

CALL DosPutMessage 

Where 

FileHandle 

Is the handle of the output file or device. 

MessageLength 

is the length of the message to be output. 

MessageBuffer 

is the buffer that contains the message to be output. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

Screen width is assumed to be 80 characters. If a word is about to 
span column 80, the word will start on a new line at column 1. 
DosPutMessage assumes the starting cursor position is column one 
when handling a word wrap. 

If the last character to be positioned on a line is a double-byte char- 
acter that would be bisected, the rule above insures that the char- 
acter is not bisected. 
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Purpose 

DosQCurDir gets the full path name of the current directory for the 
requesting process for the specified drive. 

Calling Sequence 

EXTRN DosQCurDir: FAR 

PUSH WORD DriveNumber ; Drive number 
PUSH© OTHER DirPath ; Directory path buffer (returned) 

PUSH© WORD DirPathLen ;Di rectory path buffer 

; length (returned) 

CALL DosQCurDi r 

Where 

DriveNumber 

is the drive number, for example: 

0 = default 

1 = A 

DirPath 

is where the system returns the full directory path name. 
DirPathLen 

is the length of the DirPath buffer. When DosQCurDir is called, 
this field must contain the length of the directory path buffer. If an 
error is returned by DosQCurDir because the buffer is too small, 
the DirPathLen field is updated with the required length. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

The drive letter is not part of the returned string. The string does not 
begin with a baclcslash and is terminated by a byte containing OOH. 
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Purpose 

DosQCurDisk determines tlie current default drive for tlie requesting 
process. 

Calling Sequence 

EXTRN DosQCurDisk: FAR 

PUSH@ WORD DriveNumber ; Default drive number (returned) 

PUSH@ DWORD Logical DriveMap ; Drive/map area (returned) 

CALL DosQCurDisk 

Where 
DriveNumber 

is where the system returns the number of the default drive, for 
example:, 1=A, 2=B... 

LogicalDrlveMap 

is a bit map (stored in the low-order portion of the 32-bit, double 
word area) in which the system returns the mapping of the logical 
drives. Logical Drives A to Z have a one-to-one mapping with the 
bit positions 0 to 25 of the map. 

If bit value = 0 

the logical drive does not exist. 

If bit value = 1 

the logical drive exists. 

Returns 

AX = 0 

Remarks 

None 
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Purpose 

DosQFHandState queries the state of the specified file. 
Calling Sequence 

EXTRN DosQFHandState: FAR 

PUSH WORD FIleHandle ;File handle 

PUSH@ WORD Fi 1 eHandl estate ;File handle state (returned) 

CALL DosQFHandState 

Where 

FUeHandle 

is the handle of the file to be queried. 

FlleHandfeState 

is the file handle state and consists of the following bit fields: 

• Inheritance flag 

• Write/through flag 

• Fall/errors flag 

• Sharing mode field 

• Access field 

• Reserved bitfields. 

The bit field mapping is: 

Open Mode bits 5432109876543210 
DWFRRRRRISSSRAAA 

D DASD Open 

The file is opened as follows: 
lfD = 0 

FileHandle represents a file opened in the normal way. 
If D = 1 

FileHandle represents a mounted 6\sk or diskette volume 
opened for direct access. 
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/ Inheritance Flag 

If I = 0 

File handle is inherited by a spawned process resulting from a 
DosExecPgm call. 
If I = 1 

File handle is private to the current process. 
W File Writelthfough 

The file is opened as follows: 
If W = 0 

Writes to the file may be run through the DOS buffer cache. 
If W = 1 

Writes to the file may go through the DOS buffer cache but 
sectors are written (actual file I/O completed) before a syn- 
chronous write call returns. This state of the file defines it as a 
synchronous file. 

This bit is not inherited by child processes. 

F Fail/Errors 

Media I/O errors are handled as follows: 

If F = 0 

Reported through the system critical error handler. 
If F = 1 

Reported directly to the caller via return code. 

This bit is not inherited by child processes. Media I/O errors gen- 
erated through an lOCtI Category 8 function always get reported 
directly to the caller via return code. The Fail-Errors function 
applies only to non-IOCtI handle-based type file I/O calls. 

R These bits are reserved and should be set to the values returned 
by DosQFHandState in these positions. 

S Sharing Mode 

The file sharing mode field defines what operations other proc- 
esses may perform on the file. 

If S = 001 

Deny Read/Write access 
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If S = 010 

Deny Write access 
lfS = 011 

Deny Read access 
If S = 100 

Deny Neither Read or Write access (Deny None) 
Any other value is invalid. 
A Access Mode 

The file access is assigned as follows: 

If A = 000 

Read/only access 
If A = 001 

Write/only access 
If A = 010 

Read/Write access 

Any other value is invalid. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

When a critical error occurs that the application cannot handle, it may 
reset critical error handling to be done by the system. This is done by 
Issuing DosQFHandState, turning off the fail/errors bit, issuing 
DosSetFHandState and subsequently reissuing the I/O. The expected 
critical error reoccurs and passes to the system critical error handler. 
The instant in time at which the effect of this function is visible at the 
application level Is unpredictable when asynchronous I/O is pending. 

The DASD Open bit parameter is the "Direct I/O flag." It provides an 
access mechanism to a disl< or diskette volume independent of the 
file system. This mode should only be used by systems programs and 
not by application programs. 
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Purpose 

DosQFilelnfo returns Information for a specific file. 
Calling Sequence 

EXTRN DosQFilelnfo: FAR 

PUSH WORD FileHandle 

PUSH WORD FilelnfoLevel 

PUSHP OTHER FilelnfoBuf 

PUSH WORD FilelnfoBuf Size 

CALL DosQFilelnfo 

Where 

FileHandle 

Is the file handle. 

Ff7e/n/oLei^e/ 

is the level of file information required. Level 1 file information is 
returned in the following standard format and, where applicable, 
is based on the most recent DosClose or DosSetFileinfo: 



2 bytes - 


File date of creation 


2 bytes - 


File time of creation 


2 bytes - 


File date of last access 


2 bytes - 


File time of last access 


2 bytes - 


File date of last write 


2 bytes - 


File time of last write 


2 bytes - 


File end of data (low word) 


2 bytes - 


File end of data (high word) 


2 bytes - 


File allocation (low word) 


2 bytes - 


File allocation (high word) 


2 bytes - 


File attribute 


FilelnfoBuf 





is the storage area where the system returns the requested level 
of file information. 

FilelnfoBufSize 

is the length of FilelnfoBuf. 



;File handle 
;Fi1e data required 
;File data buffer 
;File data buffer size 
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Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

Level 1 is the only defined level of information. 

The date and time formats are the same as those for the directory 
entry. For more Information refer to "DosFindFirst - Find First 
Matching File" on page 2-59. 

File date/time of creation and file date/time of last access are not 
supported in this release and are returned as zeros. 
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Purpose 

DosQFileMode queries tlie mode (attribute) of tlie specified file. 
Calling Sequence 

EXTRN DosQFileMode; FAR 

PUSH© ASCIIZ Fi 1 ePathName -.File path name 

PUSH© WORD Current Attribute ;Data area (returned) 

PUSH DWORD 0 : Reserved (must be 0) 

CALL DosQFileMode 

Where 

FilePathName 

is the file path name. 

CurrentAttribute 

is where the file's current attribute is returned. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

The volume label type attribute is not returned by DosQFileMode, 
DosQFslnfo may be used for this purpose. 
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File attribute bits are defined as follows: 



UUU In 




read only file 






hidden file 


nnnAU 
U004n 




system file 


UOlOM 




subdirectory 


UU^Uri 




file archive 


UU4Un 




reserved 


UUoUn 




reserved 


0100H 




reserved 


0200H 




reserved 


0400H 




reserved 


0800H 




reserved 


1000H 




reserved 


2000H 




reserved 


4000H 




reserved 


8000H 




reserved 



These bits may be set individually or in combination. For example, 
an attribute of 0021H indicates a read-only file which should be 
archived. 
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Purpose 

DosQFslnfo queries information from a file system device. 
Calling Sequence 

EXTRN DosQFslnfo: FAR 



PUSH WORD DriveNumber 

PUSH WORD FSInfoLevel 

PUSH© OTHER FSInfoBuf 

PUSH WORD FSInfoBuf Size 

CALL DosQFslnfo 



; Drive number 

;File system data required 
;File system info buffer 
;File system info buffer size 



Where 

DriveNumber 

is the logical drive number (0 = default, 1 = A, etc.). 

FSInfoLevel 

is the level of file information required. 

Level 1 information is returned in the following standard format: 

4 bytes - File System ID 

4 bytes - Number of sectors per allocation unit 

4 bytes - Number of allocation units 

4 bytes - Available allocation units 

2 bytes - Bytes per sector 

Level 2 information is returned in the following standard format: 

4 bytes - Reserved 

1 byte - Length of Volume label (null not included) 

n bytes - Volume label ASCIIZ string 

FS/fi/oBuf 

is the storage area where the system returns the requested level 
of file information. 

FSInloBufSize 

is the length of FSInfoBuf. 
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Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

Trailing blanlcs supplied at volume label definition time are not con- 
sidered to be part of the label and are therefore not returned as label 
data. 
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Purpose 

DosQHandType determines whether a handle references a file or a 
device. 

Calling Sequence 

EXTRN DosQHandType: FAR 

PUSH WORD FileHandle ;F11e handle 

PUSH@ WORD HandType ;Handle type (returned) 

PUSH© WORD FlagWord ; Device driver attribute (returned) 

CALL DosQHandType 

Where 

FileHandle 

is the fiie handle 

HandType 

is where the system returns the value indicating the handle type. 
HandType is composed of two bytes: 

HandleClass 

describes the handle class. It may take on the following 
values in the low byte of HandleType: 

• 0 = handle is for a disk file 

• 1 = handle Is for a character device 

• 2 = handle is for a pipe. 

Values greater than 2 are reserved. 
HandleBlts 

provides further Information about the handle in the high byte 
of HandleType. This byte is broken into eight bits, whose 
meaning depends upon the value of HandleClass: 
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HandleBits Handled ass 

54321098 7 0 

Disk file Nuuuuuuu 0 
Char device Nuuuuuuu 1 
Pipe Nuuuuuuu 2 

The network bit = N. If set, it means that the handle refers to a 
remote file, device, or pipe. Otherwise, the handle refers to a 
local file, device, or pipe. 

The undefined and reserved bit = u. A program should not 
depend upon the values of these bits as they are subject to 
change. 

FlagWord 

is where the system returns the device driver's attribute word If 
HandleType indicates a local character device. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

DosQHandType allows some programs which may be Interactive or 
file-oriented to determine the source of their input. For example, 
C0MMAND.COM suppresses writing prompts if the input is from a 
disk file. 
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Purpose 

DosQueryQueue finds the size of a queue. 
Calling Sequence 

EXTRN DosQueryQueue : FAR 

PUSH WORD QueueHandle ; Handle of queue to find size 

PUSH@ WORD NumberEI ements ;S1ze of the queue (returned) 

CALL DosQueryQueue 

Where 

QueueHandle 

Is the handle of the queue to find size. 

NumberEiements 

is where the number of entries currently In the queue waiting to 
be processed are returned. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

Any process which has a queue open may issue this request. 

If the owning process closes the queue prior to this request being 
issued, the "Queue does not exist (invalid queue handle)" return code 
is returned. 
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Purpose 

DosQVerify returns the value of the verify flag. 
Calling Sequence 

EXTRN DosQVerify: FAR 

PUSH@ WORD VerifySetting -.Verify setting (returned) 
CALL DosQVerify 

Where 

VetifySeWng 

is where the current verify mode for the process is returned. 

if value = OOH 

verify mode is not active. 
if value = 01 H 

verify mode is active. 

Returns 

AX = 0 

Remarks 

None 
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Purpose 

DosRead reads the specified number of bytes from a file or device to 
a buffer location. 

Calling Sequence 

EXTRN DosRead: FAR 

PUSH WORD FileHandle ;File Handle 

PUSH© OTHER BufferArea ;User buffer 

PUSH WORD BufferLength ; Buffer length 

PUSH@ WORD BytesRead ; Bytes read (returned) 

CALL DosRead 

Where 

FileHandle 

is the file handle obtained from DosOpen. 

BufferArea 

is the Input buffer. 

BufferLength 

is the number of bytes to be read. 

BytesRead 

is where the the number of bytes read is returned. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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Family API Considerations 

Some options operate differently in the DOS mode than they do in the 
OS/2 mode. Therefore, the following restrictions apply to DosRead 
when coding in the DOS mode: 

Use only single-byte DosReads to COMx In PC/DOS. The COM 
device driver supplied with PC/DOS does not support multlple-byte 
I/O. 

Remarks 

The requested number of bytes may not be read. If the value in 
BytesRead = 0, then the program has tried to read from the end of 
file. 

The file pointer is moved to the desired position by reading, writing, 
and performing function DosChgFllePtr (Move File Read/Write 
Pointer). 



2-192 



DosReadAsync - 
Asynchronous Read from File 



Purpose 

DosReadAsync transfers the specified number of bytes from a file to a 
buffer, asynchronously with the requesting process execution. 



Calling Sequence 

EXTRN DosReadAsync: FAR 



PUSH WORD 

PUSH@ DWORD 

PUSH@ WORD 

PUSH@ OTHER 

PUSH WORD 

PUSH@ WORD 



Fi 1 eHandl e 

RamSemaphore 

ReturnCode 

BufferArea 

BufferLengtli 

BytesRead 



;File liandle 

:Ram semaphore 

;I/0 error RC (returned) 

;User buffer 

; Buffer length 

: Bytes read (returned) 



CALL DosReadAsync 



Where 

FlleHandle 

Is the file handle obtained from DosOpen. 

RamSemaphore 

is used by the system to signal the caller that the read operation 

is complete. 

ReturnCode 

is where the return code is returned. 

BuflerArea 

is the input buffer. 

BufferLength 

is the number of bytes to be read. 

BytesRead 

is where the number of bytes read is returned. 



Returns 

AX = 0 

Note: When RamSemaphore is cleared and the read operation is 
complete, ReturnCode can be checiced. 
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Remarks 

The requested number of bytes may not be read. When 
RamSemaphore is cleared, if the value in BytesRead Is 0, the 
program attempted to read from the end of the file. 

The value of the file read/write pointer Is updated before the I/O 
request is queued to the device driver. 

RamSemaphore must be set by the application before the 
DosReadAsync call Is made. The application issues the following 
sequence: 

• DosSemSet 

• DosReadAsync 

• DosSemWait. 

The program must not look at the values returned in ReturnCode, 
BufferArea, or BytesRead until after RamSemaphore is cleared. 
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Purpose 

DosReadQueue reads an element from a queue and removes it. 



Calling Sequence 

EXTRN DosReadQueue: FAR 



PUSH 

PUSH@ 

PUSH@ 

PUSH© 

PUSH 

PUSH 

PUSH@ 

PUSH 

CALL 



WORD 

DWORD 

WORD 

DWORD 

WORD 

WORD 

WORD 

DWORD 



QueueHandle 
Request 
DataLength 
DataAddress 
El ementCode 
NoWait 
ElemPriority 
SemaphoreHandl e 



; Handle of queue to read from 
; Request identification data (returned) 
; Length of element received (returned) 
; Element received 

•.Indicate want a particular element 
; Indicate to not wait if queue is empty 
; Priority of element 
; Semaphore handle 



DosReadQueue 



Where 

QueueHandle 

is tlie handle of the queue to read from. 

Request 

is an area in which the following information is returned: 

The first word is the PID of the process which added the element 
to the queue. 

The second word Is used for event encoding by the application. 
The data in this word is the same as that furnished by the Request 
parameter on the DosWriteQueue request for the corresponding 
queue element. The value of this data is understood by the client 
thread and by the server thread. There is no special meaning to 
this data and the operating system does not alter the data. 

DataLength 

Is where the length of the data being received Is returned. 
DataAddress 

Is where the address of the received element is returned. 
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ElementCode 

indicates to override the normal priority, FIFO, or LIFO read 
ordering. Tliis operand is used to identify a specific element wiiich 
is to be read. Tliis field should be set to 0 (by the application) to 
read the first element in the queue, or set to non-zero (to the value 
returned by a previous DosPeekQueue operation) to indicate read 
a peel<ed element. 

NoWait 

specifies the action to be performed when there are no entries in 
the queue. 

if value = 0 

the requesting thread waits. 

If value = 1 

the requesting thread does not wait. 

ElemPrlorlty 

is where the priority specified when the element was added to the 
queue is received. This is a numeric value In the range of 0 to 15 
with 15 being the highest priority. 

SemaphoreHandle 

is the handle of the semaphore cleared when the queue has data 
placed into it and NoWait=1 is specified. The semaphore may be 
either a RAM or system semaphore. 

If this handle is for a RAM semaphore, that semaphore must be in 
a shared segment between the queue owner's process and any 
process that issues a DosWriteQueue request to an associated 
queue. 

If multiple threads are processing elements from the queue using 
a NoWait value = 1, the same semaphore must be provided on all 
DosPeetcQueue or DosReadQueue requests. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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Remarks 

DosReadQueue retrieves and removes an element from a specified 
queue. 

if tiie queue is empty, the requesting thread is placed in a wait state 
until an element is added to the queue. If the NoWalt option is 
selected, the thread Is not placed in a wait state, but is returned with 
a code indicating there are no entries on the queue. 

If EiementCode is provided, the element indicated is returned. If 
ElementCode equals 0, the first element in the queue Is returned. 
This allows a thread to read an element from a queue and use 
DosPeekQueue to compare other elements in the queue to the one 
read. 

Only the queue owner (the process which created the queue via 
DosCreateQueue) is allowed to issue this call. Any thread within that 
process may also issue DosReadQueue calls to any queue owned by 
that process. 

The semaphore provided by SemaphoreHandle would typically be 
used with a DosMuxSemWait request to wait on a queue or other 
events. This operand is Ignored if NoWait = 0 Is specified. 
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Purpose 

DosReallocHuge changes the size of memory originally allocated by 
DosAllocHuge. 

Calling Sequence 

EXTRN DosReallocHuge: FAR 

PUSH WORD NumSeg ; Number of 65536-byte segments requested. 

PUSH WORD Size ; Number of bytes in last segment 

PUSH WORD Selector ; Selector 

CALL DosReallocHuge 

Where 
NumSeg 

is the number of 65536 byte segments requested. 
Size 

is the number of bytes requested in the last non-65536 byte 
segment. A value of 0 indicates none. 

Selector 

is the selector returned on a previous DosAllocHuge. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Family API Considerations 

Some options operate differently in the DOS mode than they do In the 
OS/2 mode. Therefore, the following restriction applies to 
DosReallocHuge when coding in the DOS mode: 

The requested Size value Is rounded up to the next paragraph. 
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Since the MaxNumSeg parameter in DosAllocHuge is ignored in the 
DOS mode, any subsequent call to DosReallocHuge will also ignore 
any previous setting of MaxNumSeg. 

Remarks 

The maximum new size is the value specified for MaxNumSeg on the 
original DosAllocHuge request. 
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Purpose 

DosReallocSeg changes the size of a segment already allocated. 
Calling Sequence 

EXTRN DosReallocSeg: FAR 

PUSH WORD Size ;New size requested in bytes 
PUSH WORD Selector ; Selector 
CALL DosReallocSeg 

Where 

size 

is the new segment size requested In bytes. A value of 0 Indicates 
65536 bytes. 

Selector 

is the selector of the segment to be resized. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Family API Considerations 

Some options operate differently in the DOS mode than in the OS/2 
mode. Therefore, the following restriction applies to DosReallocSeg 
when coding in the DOS mode: 

• the requested Size value is rounded up to the next paragraph. 
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Remarks 

DosReallocSeg is supported for shared and unshared segments. 
Shared segments can be Increased but not decreased in size. 

Note that a call to DosReallocSeg referencing a discardable segment 
(a segment which was allocated via DosAllocSeg with AllocFlags bit 2 
(0100B) set) will, in addition to reallocating the memory, perform the 
same action as a call to DosLockSeg. Refer to "DosLockSeg — 
Lock Segment in Memory" on page 2-112 for more information about 
this option. 

Note: Data in segments discarded in low-memory situations is not 
retained. The only way to reference the discarded segments again is 
to reallocate them. 

DosReallocHuge is used to change the size of memory allocated with 
DosAllocHuge. 
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Purpose 

DosResumeThread restarts a thread previously stopped by way of the 
DosSuspendThread system call. 

Calling Sequence 

EXTRN DosResumeThread : FAR 

PUSH WORD ThreadlD ;Thread ID of thread to resume 
CALL DosResumeThread 

Where 

ThreadlD 

is the Thread ID of the thread to be resumed. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

None 
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Purpose 

DosRmDir removes a subdirectory from the specified 6\sk. 
Calling Sequence 

EXTRN DosRmDir: FAR 

PUSH© ASCIIZ DirName : Directory name 

PUSH DWORD 0 ; Reserved (must be 0) 

CALL DosRmDir 

Where 

DirName 

Is tlie directory path name. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

The directory must be empty before it can be removed with the 
exception of the "." and . You cannot remove subdirectories that 
contain hidden files. The last directory name in the path is the direc- 
tory to be removed. The root directory and the current directory 
cannot be removed. 
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Purpose 

DosScanEnv scans (searches) an environment segment for an envi- 
ronment variable. 

Calling Sequence 

EXTRN DosScanEnv: FAR 

PUSH© ASCIIZ EnvVarName ; Environment variable name 
PUSH© DWORD ResultPointer ; Search result pointer (returned) 
CALL DosScanEnv 

Where 
EnvVarName 

is the name of the environment variabie to be located. Do not 
include a trailing "=", since this is not part of the name. 

ResultPointer 

is where the address of the value for the specified environment 
variable is returned. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

Assume that the processes' environment contains: 
"DPATH=c : \sysdi r ; c : \1 i bdi r" 

+.. .ResultPointer points liere after call 
to DosScanEnv below. 

DosScanEnv ("DPATH", &ResultPointer) ; 

As noted above, ResultPointer will point to the first 
character of the value of the environment variable. 
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Purpose 

DosSearchPath provides a general path search mechanism which 
aliows applications to find files residing along paths. The path string 
may come from the process environment, or be supplied directly by 
the caller. 

Calling Sequence 

EXTRN DosSearchPath: FAR 

PUSH WORD Control 

PUSH@ ASCIIZ PathRef 

PUSH@ ASCIIZ FileName 

PUSH© OTHER ResultBuffer 

PUSH WORD ResultBufferLen 

CALL DosSearchPath 

Where 

Control 

is a word bit vector which controls the behavior of DosSearchPath: 

• Bit 0 = implied current bit 

• Bit 1 = path source bit 

• Bits 2-15 = reserved bits, must be 0. 

The implied current bit controls whether the current directory is 
implicitly on the front of the search path. If the implied current bit 
= 0, DosSearchPath will only search the current directory if it 
appears in the search path. If the implied current bit = 1, 
DosSearchPath will search the current working directory before it 
searches the directories in the search path. 

For example, implied current bit = 0 and path = ".\;a;b" is equiv- 
alent to implied current bit = 1 and path = "a;b". 

The path source bit determines how DosSearchPath interprets the 
PathRef argument. If the path source bit = 0, then PathRef points 
to the actual search path. The search path string may be any- 
where in the calling processes' address space, therefore, it may 
be in the environment, but does not have to be. 



; Function control vector 
; Search path reference 
;F1le name 

; Search result buffer 
;Search result buffer length 
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If the path source bit = 1, then PathRef points to the name of an 
environment variable in the process environment, and that envi- 
ronment variable contains the search path. 

PathRef 

If the path source bit of control = 0, then PathRef is the search 
path, which may be anywhere in the caller's address space. 

If the path source bit of control = 1, then PathRef is the name of an 
environment variable which contains the search path. 

A search path consists of a sequence of paths separated by 

It is a single ASCIIZ string. The directories will be 
searched in the order they appear in the path. 

Environment variable names are simply strings which 
match name strings in the environment. The "=" sign is not 
part of the name. 

FHeName 

is the ASCIIZ file name to search for. It may contain global char- 
acters. If FileName does contain global characters, they will 
remain in the result path returned in ResultBuffer. This allows 
applications like CMD.EXE to feed the output directly to 
DosFindFlrst. If there are no wild cards in FileName, the result 
path returned in ResultBuffer will be a full qualified name, and 
may be passed directly to DosOpen, or any other system call. 

ResultBuffer 

is where the result pathname of the file is returned, if found. 

ResultBufLen 

is the length in bytes of the ResultBuffer. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 



2-206 



DosSearchPath - 
Search Path for File Name 

Remarks 

PathRef always points to an ASCIIZ string. Let DPATH be an environ- 
ment variable in the environment segment of the process. 

"DPATH=c:\sysdir;c:\init"/* in the environment */ 

The following two code fragments are equivalent: 

DosScanEnv ("DPATH", &PathRef): 
DosSearchPath (0, /* Path Source Bit = 0 */ 

PathRef, "myprog.ini", &ResultBuffer, ResultBufLen); 

DosSearchPath (2. /* Path Source Bit = 1 */ 

"DPATH", "myprog.ini", &ResultBuffer. ResultBufLen); 

Both of them use the search path stored as DPATH in the environ- 
ment segment. In the first case, the application uses DosScanEnv to 
find the variable, in the second case DosSearchPath calls 
DosScanEnv for the application. 

DosSearchPath does not check for consistency or formatting on the 
names, it does a DosFindFlrst on a series of names it constructs from 
PathRef and FileName. 

To determine the size of the returned pathname, the ResultBuffer 
must be scanned for the ASCIIZ terminator. 



I 
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Purpose 

DosSelectDisk selects the drive specified as the default drive for the 
calling process. 

Calling Sequence 

EXTRN DosSelectDisk: FAR 

PUSH WORD DriveNumber ; Default drive number 
CALL DosSelectDisk 

Where 

DriveNumber 

contains the new default drive number, where 1 = A and 2 = B., 
and so on. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

None 
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Purpose 

DosSelectSession allows a parent session to switch one of Its child 
sessions to the foreground. 

Calling Sequence 

EXTRN DosSelectSession: FAR 

PUSH WORD SessID ; Session ID 

PUSH DWORD Reserved ; Reserved (must be zero) 

CALL DosSelectSession 

Where 

SessID 

is the ID of the session to be switched to the foreground. The 
value specified for SessID must have been returned on a prior 
call to DosStartSession except that a value of 0 indicates to switch 
the caller's session, (that is, the parent session), to the fore- 
ground. 

Reserved 

is a DWORD of 0. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

DosSelectSession can only be issued by a parent session to select 
itself or a child session. DosSelectSession can not be used to select 
a grandchild session. DosSelectSession may only be used to select 
child sessions which were originally started by the caller with 
DosStartSession specifying Related equal 1. That is, sessions started 
as independent sessions can not be selected through this call. 
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When DosSelectSession is Issued, the session specified will not be 
brought to the foreground unless the parent session or one of Its 
descendant sessions is currently executing In the foreground. Other- 
wise, a unique error code Is returned in AX. 

DosSelectSession can only be issued by the process that originally 
started (using DosStartSesslon) the SessID specified. 
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Purpose 

DosSemClear unconditionally clears a semaphore. If any threads 
were blocked on the semaphore, they are restarted. 

Calling Sequence 

EXTRN DosSemClear: FAR 

PUSH DWORD SemHandle ; Semaphore handle 
CALL DosSemCI ear 

Where 

SemHandle 

Is the handle for the semaphore. For a system semaphore, this 
handle is the result of the DosCreateSem or DosOpenSem request 
which granted this process access to the semaphore. For a RAM 
semaphore, this handle is the address of the storage allocated for 
the semaphore. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

DosSemClear is typically used to release a semaphore obtained 
through DosSem Request. DosSemClear is also used with the 
semaphore signalling functions DosSemSetWait, DosSemWait, and 
DosMuxSemWait, to clear a semaphore. A semaphore is checked 
only when a process receives its time slice and if a semaphore clears 
and resets during the time it is not processing, then the process does 
not become blocked. 
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DosSemClear cannot be issued against a system semaphore owned 
by another process unless the NoExclusive option was selected on 
the DosCreateSem request that created the semaphore. However, at 
Interrupt time any thread may clear an exclusively owned 
semaphore. 
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Purpose 

DosSemRequest obtains a semaphore. If the semaphore is already 
owned, the requesting thread Is placed in a wait state until the 
semaphore is released or until a time out occurs. 

Calling Sequence 

EXTRN 

DosSemRequest: FAR 

PUSH DWORD SemHandle ; Semaphore handle 
PUSH DWORD Timeout ;Timeout 
CALL DosSemRequest 

Where 

SemHandle 

is the handle for the semaphore. For a system semaphore, this 
handle is the result of the DosCreateSem or DosOpenSem request 
which granted this thread access to the semaphore. For a RAM 
semaphore, this handle Is the address of the storage allocated for 
the semaphore. 

Timeout 

is the time, in milliseconds, until the requesting thread resumes 
execution if the requested semaphore did not become available. 
The meaning of the values specified are: 

If value = -1 

there is no time out, if the semaphore is owned. The requestor 
waits indefinitely. 
If value = 0 

there is an immediate return if the semaphore is owned. 
If value >0 

the value is the number of milliseconds to wait if the 
semaphore is owned. 
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Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

DosSemRequest checks the status of the semaphore. If a semaphore 
Is unowned, DosSemRequest sets it owned and returns immediately 
to the caller. If the semaphore is owned, DosSemRequest can 
optionally block the thread until It is unowned, then try again. The 
Timeout parameter places an upper bound on the amount of time to 
block before returning even though the semaphore is owned. 

When a thread owns a semaphore, it is invalid for another thread to 
issue a semaphore request that changes the state of that semaphore, 
unless the NoExclusive option is specified. However, at interrupt 
time, any thread may clear any exclusive, owned, semaphore. For 
exclusive system semaphores, recursive requests for system 
semaphores are supported by means of a use count of the number of 
times the owner has issued a DosSemRequest without a corre- 
sponding DosSemClear. When a thread owns a semaphore it is 
invalid for another thread to Issue any semaphore request such as, 
(DosSemClear), that will change the state of the semaphore unless 
the NoExclusive option was specified in the original DosSemRequest. 

The unblocking of a DosSemRequest does not return unless the indi- 
cated semaphore remains clear until the affected thread is redis- 
patched and is able to claim It. This procedure Is known as "level 
triggered" unblocking. 

RAM semaphores are generated by a doubleword in RAM. The 
doubleword initialized to 0 Indicates the semaphore is unowned. 

Note: An application can issue DosSemSet if it requires a 
semaphore to be initially set to owned. 

System semaphores are generated by a semaphore data structure 
allocated by DosCreateSem, and controlled by OS/2. System 
semaphores are initialized to unowned. However, if an application 
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requires the semaphore to be initially set to owned, issue DosSemSet 
after DosCreateSem. 

If a thread terminates while it owns a system semaphore, the 
ERROR_SEM_OWNER_DIED return code is returned to the thread that 
gets the next semaphore via DosSemRequest. That thread takes 
steps to ensure the integrity of the resource. The thread can release 
the resource by issuing a DosSemClear or it can reset the 
ERROR_SEM_OWNER_DIED error condition flagged in the 
semaphore data structure. 

When a thread no longer requires the protected resource, it issues 
DosSemClear and sets the semaphore unowned. Any threads that 
were blocked waiting for that semaphore are started at this time. 

Before owned system semaphores are freed, issue DosExitList. This 
allows a process to clean up the current resource before it terminates 
and avoids receiving any error code. 
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Purpose 

DosSemSet unconditionally sets a semaphore. 
Calling Sequence 

EXTRN DosSemSet: FAR 

PUSH DWORD SemHandle ; Semaphore handle 
CALL DosSemSet 

Where 

SemHandle 

is the handle for the semaphore. For a system semaphore, this is 
the result of the DosCreateSem or DosOpenSem request which 
granted this thread access to the semaphore. For a RAM 
semaphore, this handle is the address of the storage allocated for 
the semaphore. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

DosSemSet is not required in a resource control environment using 
DosSemRequest and DosSemClear. However, it Is typically used in a 
signaling environment implemented via DosSemClear, DosSemWait, 
and DosMuxSemWait. These function calls can be used in combina- 
tion with DosSemClear and DosSemSet to awal^en a blocl<ed thread 
whenever a semaphore Is cleared rather than when it Is no longer 
owned. 

Note: DosSemSet cannot be issued against a system semaphore 
which is owned by another process unless the NoExclusive option 
was selected on the original DosCreateSem request. 
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Purpose 

DosSemSetWait blocks the current thread until the next DosSemClear 
is issued. However, DosSemSetWait does not establish ownership of 
this semaphore. 

Calling Sequence 

EXTRN DosSemSetWait: FAR 

PUSH DWORD SemHandle ; Semaphore liandle 
PUSH DWORD Timeout ;Timeout 
CALL DosSemSetWait 

Where 

SBmHandle 

is the handle for the semaphore. For a system semaphore, this 
handle is the result of the DosCreateSem or DosOpenSem request 
that granted this thread access to the semaphore. For a RAM 
semaphore, this handle is the address of the storage allocated for 
the semaphore. 

Timeout 

is the time, in milliseconds, until the requesting process is to 
resume execution if the requested semaphore does not become 
available. The meaning of the values specified are 

If value = -1 

there is no timeout, if a DosSemClear Is not issued. The 
requestor waits Indefinitely. 

If value = 0 

there is an immediate return. 

If value > 0 

value is the number of milliseconds to wait if a DosSemClear 
is not issued. 
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Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

DosSemSetWait is set before tlie thread is blocl<ed, if the semaphore 
is not initially set. The semaphore resets on return. 

The unblocking of DosSemSetWait does not return unless the indi- 
cated semaphore remains clear until the affected thread Is redis- 
patched and determines the semaphore Is clear. This is known as a 
"level triggered" procedure. 

DosSemSetWait cannot be issued against a system semaphore 
owned by another thread unless the NoExclusive option was selected 
on the DosCreateSem request that created the semaphore. If a 
system semaphore is created with the exclusive option, 
DosSemSetWait should not be used to coordinate execution between 
threads. The owner must clear this semaphore. 
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Purpose 

DosSemWait blocks the current thread until an indicated semaphore 
clears, but does not establish ownership of the semaphore. 

Calling Sequence 

EXTRN DosSemWait: FAR 

PUSH DWORD SemHandle ; Semaphore handle 

PUSH DWORD Timeout ;T1meout 

CALL DosSenlWalt 

Where 
SemHandle 

is the handle for the semaphore. For a system semaphore, this 
handle is the result of the DosCreateSem or DosOpenSem request 
that granted this thread access to the semaphore. For a RAM 
semaphore, this handle Is the address of the storage allocated for 
the semaphore. 

Timeout 

is the time, In milliseconds, until the requesting process is to 
resume execution if the requested semaphore does not become 
available. The meaning of the values specified are: 

If value = -1 

there is no time out if the semaphore is set. The requestor 
waits indefinitely. 

If value = 0 

there is an immediate return if the semaphore is set. 
If value > 0 

the value is the number of milliseconds to wait if the 
semaphore is set. 
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Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

The unblocking of DosSemWait does not return unless the Indicated 
semaphore remains clear until the affected thread has been redis- 
patched and determines that the indicated semaphore is clear. This 
Is known as a "level-triggered" procedure. 
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Purpose 

DosSendSignai sends a CTL-C or CTL-Break signal to the last 
process In the command subtree (leaf-most) that has a corresponding 
signal handler installed. A command subtree is all of the processes 
created as a result of a single command. 

Calling Sequence 

EXTRN DosSendSignai: FAR 

PUSH WORD PID ;PID of root of subtree 

PUSH WORD SigNumber ; Signal Number to send 
CALL DosSendSignai 

Where 

PID 

is the process ID of the root process of the subtree. It is not nec- 
essary that this process still be alive, but It is necessary that this 
process be a direct child of the process which issues this call. 

SigNumber 

is the signal to send. It may be: 

• 1 - Ctrl-C (SIGINTR) 

• 4 - Ctrl-Break (SIGBREAK) 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

The signal is sent by descending the process tree to the leaf-most 
process. Then starting with that process, look for one that has a 
handler installed for the corresponding signal. If a handler is found, 
give the signal to that process. Otherwise look at the parent process. 
Continue until either the signal is sent or the original process is 
looked at. The latter case is indicated by a unique error code. 
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Purpose 

DosSetCp allows a process to set Its code page and the session's 
display code page and keyboard code page. 

Calling Sequence 

EXTRN DosSetCp: FAR 

PUSH WORD CodePage ;Code page identifier 

PUSH WORD Reserved ;Reserved, set to O 

Cal 1 DosSetCp 



Where 
CodePage 

is a code page identifier word that has one of the following values: 

Identifier Description 

437 IBM PC US 437 code page 

850 Multilingual code page 

860 Portuguese code page 

863 Canadian-French code page 

865 Nordic code page 

Reserved 

is a reserved word that must be set to 0. 



Returns 

IF AX = 0 then no error 
ELSE AX = error code. 



Remarks 

DosSetCp allows a program to set its code page. See CONFIG.SYS 
and the CODEPAGE command for preparing code pages for the 
system. The first code page specified in the CODEPAGE command is 
the default system code page. The session code page of a new 
session is set to the default system code page. A session's code 
page can be changed by the user with the CHOP command at the 
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command prompt. The process code page of a new program started 
from a session command prompt is set to that session's code page. 

DosSetCp sets the process code page of the calling process. The 
code page of a process is used in the following ways. First, the 
printer code page is set to the process code page through the file 
system and printer spooler (the system spooler must be installed) 
when the process makes an open printer request. Calling DosSetCp 
does not affect the code page of a printer opened prior to the call and 
does not affect the code page of a printer opened by another process. 
Second, country dependent information will, by default, be retrieved 
encoded in the code page of the calling process. And third, a newly 
created process inherits its process code page from its parent 
process. 

DosSetCp also sets, in the session to which the calling process 
belongs, the code page for the session's default logical keyboard and 
automatically flushes the keyboard buffer. It also sets the display 
code page for the session's logical display. This setting of the code 
page for the session's default logical keyboard and display overrides 
any previous setting by DosSetCp, KbdSetCp, and VioSetCp by any 
process in the same session. 

Also see DosSetProcCp. 
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Purpose 

DosSetDateTime is used to set the date and time that are maintained 
by the operating system. 

Calling Sequence 

EXTRN DosSetDateTI me : FAR 

PUSH? OTHER DateTime ;Date/time structure 
CALL DosSetDateTime 



Where 
DateTime 

is a structure that contains the following data items: 



BYTEO 


- Hours is the new hour. 


BYTE 1 


- Minutes is the new minute. 


BYTE 2 


- Seconds is the new second. 


BYTES 


- Hundredths is the new hundredths of a second. 


BYTE 4 


- Day is the day to be set. 


BYTES 


- Month is the month to be set. 


WORD 6 


- Year is the year to be set. 


WORDS 


- TimeZone minutes from UTO. 



Note: The numbers values listed in the above structure represent 
decimal offsets. 



Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

The DayofWeeIc value is based on Sunday = to 0. TimeZone is the 
difference in minutes between the current time zone and UTO. This is 
a positive number if earlier than UTO and a negative number if later. 
For Eastern Standard Time this value would be 300 (5 hours earlier 
than UTO). 
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Purpose 

DosSetFHandState sets the state of the specified fiie. 
Calling Sequence 

EXTRN DosSetFHandState : FAR 

PUSH WORD FlleHandle ;Fi1e handle 

PUSH WORD Fi1eHand1 estate ;F11e handle state 
CALL DosSetFHandState 

Where 

FlleHandle 

is the handle of the file to be set. 

FileHandleState 

is the fiie handle state and consists of the following bit fields: 

• Inheritance flag 

• Write-through flag 

• Fail-errors flag 

• Zero bit field. 

File Handle State Bits 

5432109876543210 
OWFRRRRRIOOOROOO 

I Inheritance Flag 

If I = 0 

File handle is inherited by a spawned process resulting 
from a DosExecPgm call. 
If I = 1 

File handle is private to the current process, x 
W File Write-through 

The file is opened as follows: 
If W = 0 

Writes to the file may be run through the DOS buffer cache. 
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If w = 1 

Writes to the file may go through the DOS buffer cache but 
the data is written (actual file I/O completed) before a syn- 
chronous write call returns. This state of the file defines it 
as a synchronous file. 

This bit is not inherited by child processes. 

F Fail-Errors 

Media I/O errors are handled as follows: 

If F = 0 

Reported through the system critical error handler. 
If F = 1 

Reported directly to the caller by way of the return code. 

This bit is not inherited by child processes. Media I/O 
errors generated through an lOCtI category eight function 
always get reported directly to the caller via return code. 
The Fail-Errors function applies only to non-IOCtI 
handle-based type file I/O calls. 

0 Zero bits 

These bits must be set to zero. Any other values for 
FileHandleState are invalid 

R Reserved bits 

These bits are reserved and should be set to the values 
returned by DosQFHandState in these positions. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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Family API Considerations 

Some options operate differently in tlie DOS mode tlian they do in 
OS/2 mode. Tlierefore, the following restrictions apply to 
DosSetFHandState when coding in the DOS mode: 

• for FileHandle, the validity of the handle is not checked. 

• Inheritance Flag must be set equal to zero. 

• Write-through Flag must be set equal to zero. 

• Fail-Errors Flag must be set equal to zero. 

Remarlcs 

OS/2 does not guarantee the order in which sectors are written, for 
multiple sector writes. If an application requires several sectors 
written in a specific order, the operator should issue them as sepa- 
rate synchronous write operations. Setting the synchronous (nonbuf- 
fered) I/O flag does not affect any previous writes. That data may 
remain in the buffers. 

When a critical error occurs and the application cannot solve it, crit- 
ical error handling is reset to be done by the system. This is done by 
issuing DosSetFHandState and subsequently re-issuing the I/O. The 
expected critical error will re-occur and be passed to the system crit- 
ical error handler. The instant in time at which the effect of this func- 
tion is visible at the application level is unpredictable when 
asynchronous I/O is pending. 

The file handle state bits set by this function can be queried by 
DosQFHandState. 
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Purpose 

DosSetFilelnfo specifies information for a file. 
Calling Sequence 

EXTRN DosSetFileInfo:FAR 

PUSH WORD FileHandle 

PUSH WORD F11eInfoLeve1 

PUSH© OTHER FilelnfoBuf 

PUSH WORD FilelnfoBuf Size 

CALL DosSetFilelnfo 

Where 

FileHandle 

is the file handle. 

FllelnfoLevel 

is the level of file information being set. Level 1 information is 
specified in the following standard format: 

2 bytes - File date of creation 

2 bytes - File time of creation 

2 bytes - File date of last access 

2 bytes - File time of last access 

2 bytes - File date of last write 

2 bytes - File time of last write 

FilelnfoBuf 

is the storage area where the system gets the file information. 

FilelnfoBufSIze 

is the length of FilelnfoBuf. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 



;File handle 

;File info data required 
;File info buffer 
;File info buffer size 
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Remarks 

Level 1 is currently the only defined level of information. The date 
and time formats are the same as those for the directory entry. 

The DosSetFilelnfo level 1 structure is a prefix of the DosQFilelnfo 
level 1 structure. 

DosSetFilelnfo will work only for files opened in a mode that allows 
write-access. 

A zero value in the date and time components of a field does not 
change the field. For example, if both "last write date" and "last 
write time" are specified as zero in the level one information struc- 
ture, then both attributes of the file are left unchanged. If either "last 
write date" or "last write time" are specified as non-zero, then both 
attributes of the file will be set to the new values. 
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Purpose 

DosSetFileMode changes the mode (attribute) of the specified file. 
Calling Sequence 

EXTRN DosSetFileMode: FAR 

PUSH© ASCIIZ FileName jFile path name 

PUSH WORD NewAttribute ;New attribute of file 

PUSH DWORD 0 ; Reserved (must be zero) 

CALL DosSetFileMode 

Wiiere 

FileName 

is the file path name. 

NewAttribute 

is the file's new attribute. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

Attributes for Volume Label (0008H) and Subdirectory (0010H) cannot 
be changed using DosSetFileMode. If the above referenced attributes 
are used to change a file's mode, an error code is returned. 
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File attributes are defined as foilows: 

00011-1 = read oniy file 
0002H = lildden file 
0004H = system file (excluded from 
normal directory searches) 



0008H 




volume label 


001 OH 




subdirectory 


0020H 




file archive 


0040H 




reserved 


0080H 




reserved 


0100H 




reserved 


0200H 




reserved 


0400H 




reserved 


0800H 




reserved 


1000H 




reserved 


2000H 




reserved 


4000H 




reserved 


BOOOH 




reserved 
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Purpose 

DosSetFslnfo sets information for a file system device. 
Calling Sequence 

EXTRN DosSetFslnfo: FAR 

PUSH WORD DriveNumber ; Drive number 

PUSH WORD FSInfoLevel ;File system data type 

PUSH@ OTHER FSInfoBuf jFile system info buffer 

PUSH WORD FSInfoBuf Size ;File system info buffer size 

CALL DosSetFslnfo 

Where 

DriveNumber 

is the logical drive number, for example, 0 = default and 1 = A. 

FSInfoLevel 

is the level of file information to be set. 

Level 2 information is specified in the following standard format: 

1 byte = length of Volume Label (null not included) 
N bytes = Volume Label ASCilZ string 

FSInfoBuf 

is the storage area where the system gets the new file system 
information. 

FSInfoBufSIze 

is the length of FSInfoBuf. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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Remarks 

Trailing blanks supplied at volume label definition time are not 
returned by DosQFslnfo. 

File system information can only be set if the volume is opened in a 
mode that allows write-access. 



2-233 



DosSetMaxFH - 

Set Maximum File Handles 



Purpose 

DosSetMaxFH defines the maximum number of file handles for the 
current process. 

Calling Sequence 

EXTRN DosSetMaxFH: FAR 

PUSH WORD NumberHandl es ; Number of file handles 
CALL DosSetMaxFH 

Where 

NumbBrHandles 

is the total number of file handles to be provided. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

All currently open file handles are preserved. 
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Purpose 

DosSetProcCp allows a process to set Its code page. 
EXTRN DosSetProcCp: FAR 

PUSH WORD CodePage ;Code page identifier 

PUSH WORD Reserved ; Reserved 

Cal 1 DosSetProcCp 

Where 

CodePage 

Is a code page identifier word that has one of the following values: 

Identifier Description 

437 IBM PC US 437 code page 

850 Multilingual code page 

860 Portuguese code page 

863 Canadian-French code page 

865 Nordic code page 

Reserved 

is a reserved word that must be set to zero. 
Returns 

IF AX = 0 then no error 
ELSE AX = error code. 

Remarks 

DosSetProcCp sets the process code page of the calling process. 
The code page of a process is used in the following ways. First, the 
printer code page is set to the process code page through the file 
system and printer spooler (the system spooler must be installed) 
when the process makes an open printer request. Calling 
DosSetProcCp does not affect the code page of a printer opened prior 
to the call and does not affect the code page of a printer opened by 
another process. Second, country dependent information will, by 
default, be retrieved encoded in the code page of the calling process. 
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And third, a newly created process inherits its process code page 
from its parent process. DosSetProcCp does not affect the display or 
keyboard code page. 

Also see DosSetCp. 
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Purpose 

DosSetPrty allows the caller to change the base priority of a child 
process or thread in the current process. 



Calling Sequence 

EXTRN DosSetPrty: FAR 

PUSH WORD Scope ; Indicate scope of change 

PUSH WORD PriorityClass ; Priority class to set 

PUSH WORD Priori tyDelta ; Priority delta to apply 

PUSH WORD ID ; Process or thread ID 

CALL DosSetPrty 



Where 

Scope 

is used to define the scope of the request. 
If value = 0 

the priority of the indicated process and all its threads will be 
changed. Any process may be specified. 
If value = 1 

the priority of the indicated process and all its threads will be 
changed with the priorities of ail descendant processes, 
(except detached processes) and their threads will be 
changed. The indicated process must be the current process, 
or must have been created by the current process as a 
non-detached process. When the indicated process is termi- 
nated, its descendants can still be accessed. 
If value = 2 

the priority of a single thread within the current process will be 
changed. 

PriorityClass 

is used to set the priority class of a process. The values and their 
meanings are: 
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0 = no change, leave as is 

1 = idle-time 

2 = regular 

3 = time-critical 

PrlorityDelta 

is the delta priority to apply to the process's current base priority 
level. This value must range from -31 to +31. 

ID is either a process ID (scope = 0 or 1) or a thread ID (scope = 2). 
If this operand is equal to 0, the current process or thread is 
assumed. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

The OS/2 scheduler has a concept of priority classes and priority 
levels. Through this system call, threads may move between classes 
in response to changes in their execution environments. Within each 
class, a thread's priority level may vary either through system action 
or through this system call. System initiated priority variation is per- 
formed as a combination of a specific thread's actions and the overall 
system activity. 

Priority Classes A Time-Critical thread is one of the highest priority. 
Any runable Time-Critical threads, will execute before any Regular or 
Idle-Time threads. Time-Critical threads have a static priority which 
is not varied by OS/2. They are scheduled among themselves in pri- 
ority order with round-robin scheduling of threads of equal priority. 

The majority of threads fall into the Regular thread class. The priority 
level of a Regular thread is varied by OS/2 around a base value 
according to the activity of the thread and the system at any time. 
The base value is set by the thread itself. 

An Idle-Time thread is low priority and executes only when there are 
no Regular or Time-Critical threads to execute. Idle-Time threads 
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have a static priority that is not varied by OS/2. They are scheduied 
among themselves in priority order with round-robin scheduling of 
threads of equal priority. 

Priority Leveis: For each of the above priority classes, there are 32 
distinct priority levels, 0 to +31. Whenever this request is issued 
specifying a priority class, the base defaults to 0 for the new class if 
not otherwise specified. 

A process priority consists of a computed priority value that is based 
upon the process's display status (foreground or background), its 
recent I/O and processor time-usage history, and other factors. A 
user-settable value is added to the computed priority to produce the 
actual priority used by the scheduler. Thus, specifying a larger pri- 
ority allows a process to obtain better Processor scheduling than it 
normally would. A smaller priority gives the process less Processor 
resource than it would normally receive. 

The argument to this call specifies a signed delta value. That value is 
added to the current priority, the result is restricted to the legal range 
based on the process current Priority Class. 

When used with PriorityClass to change to a different class, the delta 
value applies to the base priority. If PriorityClass is specified, then a 
new base level of 0 will be assigned the target thread and any 
PriorityDelta specified will be relative to 0. 

The process ID argument specifies which process is to be affected by 
the call. The Scope determines the extent of the priority change. A 
process may change the its own priority, of any process which is a 
descendent, or of one of its threads. When changing the priority of 
another process or its descendents, only the default priority is 
changed. Any thread which has specifically changed its priority is 
unaffected. 

When a thread is created, it is initially dispatched in the same class 
and priority as its parent. 
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Purpose 

DosSetSession sets the status of a child session. 
Calling Sequence 

EXTRN DosSetSession: FAR 

PUSH WORD SessID ;Session ID 

PUSH@ OTHER StatusData ; Session status data 

CALL DosSetSession 

Where 

SessID 

Is the ID of the target session. The value specified for SessID 
must have been returned on a prior call to DosStartSession. 

StatusData 

is a structure that contains the session status data. 

Size Description 

WORD Length 

WORD Selectind 

WORD Bondind 

Length 

is the length of the data structure in bytes including Length itself. 
This value should be 6. 

Selectind 

specifies whether the target session should be flagged selectable 
or non-selectable. 

If value = 0 

leave current setting unchanged. 
If value = 1 

selectable 
If value = 2 

non-selectable 
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Bondind 

specifies which session to bring to the foreground the next time 
the parent session is selected. 

If value = 0 

leave current setting unchanged 

If value = 1 

establishes a bond between the parent session and the child 
session. The child session is brought to the foreground the 
next time the parent session is selected. If the child session is 
selected, the child session is brought to the foreground. 

If value = 2 

specifies to bring the parent session to the foreground the next 
time the parent session is selected and to bring the child 
session to the foreground if the child is selected. Any bond 
previously established with a child session is broken. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

DosSetSession sets/resets one or both of the following parameters 
related to a child session. The parameters can be set individually. 
Either parameter can be changed without affecting the current setting 
of the other. 

• Selectable/non-selectable: This parameter allows a parent 
session to set one of Its child sessions selectable or 
non-selectable. 

• Bond/no bond: This parameter allows a parent session to bond 
one of its child sessions to itself. This means if the operator 
selects the parent session from the Program Selector the child 
session is brought to the foreground. 

These parameters affect selections made by the operator from the 
Program Selector Switch list, however, they do not affect selections 
made by the parent session. When a parent session selects its own 
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session, the parent is brought to the foreground even if a bond Is in 
effect. When a parent session selects a child session, the child is 
brought to the foreground even if the parent had set the child 
non-selectable. 

DosSetSession may only be issued by a parent session for a child 
session. Neither the parent session nor any grandchild, may be the 
target of this call. DosSetSession may only be used to change the 
status of child sessions which were originally started by the caller 
with DosStartSession specifying Related equal 1. 

A bond established between a parent session and a child session can 
be broken by reissuing DosSetSession and specifying either 

Bondind = 2 to break the bond, or 

Bondind = 1 to establish a bond with a different child session. In 
this case the bond with the previous child is broken. 

Assume a bond is established between session A and its immediate 
child session B. Assume another bond is established between 
session B and its immediate child session C. Now if the operator 
selects session A session C is brought to the foreground. However, if 
session A selects its own session, session A is brought to the fore- 
ground. If session A selects session B, session C is brought to the 
foreground. Note that, in the latter case, the bond between B and C is 
honored. 

Assume a bond is established between session A and its immediate 
child session B, and assume B is non-selectable. The operator 
cannot select session B directly. However, if the operator selects 
session A, session B is brought to the foreground. 

A parent session can run in either the foreground or background 
when DosSetSession is issued. DosSetSession can only be issued by 
the process that originally started (using DosStartSession) the SessID 
specified. 
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Purpose 

DosSetSigHandler notifies OS/2 of a liandier for a signai. It may also 
be used to ignore a signal or install a default action for a signal. 



Calling Sequence 

EXTRN DosSetSigHandler: FAR 



PUSH@ OTHER Routine 



PUSH@ DWORD 

PUSH© WORD 

PUSH WORD 

PUSH WORD 



PrevAddress 

PrevAction 

Action 

SigNumber 



CALL DosSetSigHandler 



: Signal handler 
;Previous handler (returned) 
; Previous action (returned) 
; Indicate request type 
•.Signal number of interest 



Where 

Routine 

entry point of routine wtiich Is to receive control when a signal 
equal to SigNumber is issued. 

PrevAddress 

is where the address of the previous signal handler is returned. 
This operand may be coded as null (= 0) in which case it will be 

Ignored. 

PrevAction 

is where the Action of the previous signal handler is returned. 
Only values 0 to 3 are returned. This operand may be coded as 
null (= 0) in which case it will be ignored. 

4ct/on 

is an indicator of the type of request: 
If value = 0 

the system default action is installed for the signal. 
If value = 1 

the signal Is to be ignored. 
If value = 2 

the routine receives control when the SigNumber occurs. 
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If value = 3 

it Is an error for any program to signal this SigNumber to this 
process. 
If value = 4 

the current signal is reset without affecting the disposition of 
the signal. 

SigNumber 

Is the signal number to be Intercepted by this signal handler. The 
signal numbers defined are: 



Number Term 

1 (SIGINTR) 

3 (SIGTERM) 

4 (SIGBREAK) 
5 

6 
7 



Definition 

Ctrl-C 

program terminated 
Ctrl-Break 
Process flag A 
Process flag B 
Process flag C 



The following chart indicates what signal to specify to cause the 
signal handler to get control for the CTRL-C and CTRL-Break key 
sequences in each of the keyboard modes (ASCII and Binary): 





ASCII Mode 


BINARY r^ode 


CTRL-C 


SIGINTR 




CTRL-Break 


SIGINTR 


SIGBREAK 



Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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Family API Considerations 

Some options operate differently in the DOS mode than they do in 
OS/2 mode. Therefore, the following restriction applies to 
DosSetSigHandler when coding in real mode: 

The only signal recognized in DOS is SIGINTR (Ctrl-C). 

SIGINTR is fully supported, and SIGBREAK is related to SIGINTR. 
Therefore, if SIGINTR is specified, both SIGINTR and SIGBREAK are 
transferred to the SIGINTR handler. SIGBREAK is permitted as a 
coded value, but the request to set SIGBREAK is ignored. To be com- 
patible in all environments, SIGBREAK and SIGINTR should be con- 
sidered together in all cases. 

Remarlcs 

When the signal indicated by SigNumber occurs, the signal handling 
routine receives control with: 

(SS:SP) = far return address 
(SS:SP + 4) = SigNumber being processed 
(SS:SP+6) = SigArg furnished on the DosFlagProcess request, if 
appropriate. 

Other than SS, SP, OS, IP and flags, all other registers contain the 
same values they contained at the time the signal was received. The 
handler may exit by executing an intersegment return instruction, or 
by manually setting the stack frame to some known state and jumping 
to some known location. If the former option is selected, execution 
will resume where it was interrupted, and all registers will be 
restored to their values at the time of the interruption. 

The signal handler is given control under the first thread of a process, 
not a thread created by the DosCreateThread system request. 

To return from the signal, the handler must remove the signal number 
and signal argument passed as parameters. For handlers written in 
most high-level languages, this is done automatically. A handler 
written In assembly language must execute a far RET 4 Instruction or 
its equivalent, to return to the caller. 
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The signal handler may also reset the stack pointer to some previous 
valid stack frame and jump to some other part of the program. 

The values returned in Prev Address and PrevAction are to be used 
for restoring the previous signal handler when the current process no 
longer wishes to intercept this signal. For Action = 4, no values will 
be returned for PrevAddress or PrevAction. 

When a signal is issued from the base keyboard device driver in 
response to a Ctrl-C or Ctrl-Break key press, the default action will 
terminate the process if the application did not install a signal 
handler for any signal numbers 1-4. 

It will be invalid to Issue this system call when thread 1 has termi- 
nated. If thread 1 terminates with other threads still active, all signals 
will be reset to the default action. 

For signals of type SIGINTR or SIGBREAK, a call to 
DosSetSigHandier also determines which process within the current 
session will be signalled as a result of a device driver call to Device 
Helper Services for the SendEvent function and CTRL-C (or 
CTRL-BREAK) event type (see the OS/2 Technical Reference, Volume 
1, chapter nine for Device Helper Services discussion). This process 
is known as the "signal focus" for SIGINTR (or SIGBREAK) within its 
session. The signal focus for SIGINTR need not be the same process 
as the signal focus for SIGBREAK. The signal focus for a session is 
determined as follows: 

Initially, a session has no signal focus for SIGINTR (or SIGBREAK). A 
process becomes the signal focus for SIGINTR ( or SIGBREAK) within 
its session If It calls DosSetSigHandier with ActlonCode equal to 1, 2, 
or 3. A process remains the signal focus until; 

• the process terminates. 

• the process calls DosSetSigHandier with ActlonCode equal to 0. 

• another process calls DosSetSigHandier with ActlonCode equal 
to 1, 2, or 3. 

In the first two cases, the parent or most closely related ancestor 
process that has a handler installed for the appropriate signal 
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becomes the focus. If no eligible process exists, the session ceases 
to have a signal focus for that signal. 

If a device driver makes a SendEvent call for CTRL-C or 
CTRL-BREAK and the current session has no focus for the corre- 
sponding signal, all processes in the session are signaled with 
SIGTERM to terminate. 
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Purpose 

DosSetVec allows a process to register an address to be used when a 
machine exception occurs. 

Calling Sequence 

EXTRN DosSetVec: FAR 

PUSH WORD VecNum ; Function request code 

PUSH@ OTHER Routine -.Handler routine 

PUSH@ DWORD PrevAddress ; Previous handler address (returned) 

CALL DosSetVec 

Where 

VecNum 

is the nunnber of the vector to be serviced by this routine. Legal 
numbers are: 

00 = divide overflow 

04 = overflow 

05 = bound 

06 = invalid opcode 

07 = processor extension not available 
16 = processor extension error 

Routine 

Is a routine to be entered when the exception occurs. If this 
parameter is 0, any previous address is de-registered. 

PrevAddress 

is where the address of the previous handler routine is returned. 
This is provided so a handler may be set then later restored to the 
previous handler. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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Family API Considerations 

Some options operate differently in the DOS mode than they do in 
OS/2 mode. Therefore, the following restriction applies to DosSetVec 
when coding In the DOS mode: 

• VecNum = 7 not supported. 
Remarics 

DosSetVec allows a process to register an address to be used when a 
machine exception occurs. The process is analogous to setting an 
address In the interrupt vector table when running In 8086 mode. 

Should an exception occur, and the process has registered a handler, 
that handler is entered as If Its address had been stored in the CPUs 
interrupt vector, except that Interrupt is still enabled. If no address 
has been registered for that vector, the process is terminated. 

When a process registers an exception handler for VecNum 7 
(processor extension not available) the machine status word (MSW) 
for that process will be set to Indicate a numeric processor extension 
(NPX) 287 is not present in the machine. The Emulate bit will be set 
and the Monitor Processor bit will be reset. This is done without 
regard for the true state of the hardware. 

When a process de-registers a handler for VecNum 7, the MSW will 
be set to reflect the true state of the hardware. 

When an NPX287 exception is being processed, the NPX287 status 
word will be passed to the exception handler by being pushed on the 
stack prior to the exception handler being involved. When the excep- 
tion handler has completed execution, this word must be popped from 
the stack before an IRET is Issued to return to the exception handler 
Interface routine. 
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Purpose 

DosSetVerify sets the verify switch. 
Calling Sequence 

EXTRN DosSetVerify: FAR 

PUSH WORD VerifySetting ;New value of verify switch 
CALL DosSetVerify 

Wiiere 

VerlfySeWng 

is the new state of Verify Mode for the requesting process. 

If value = 0 

verify mode is deactivated. 
If value = 1 

verify mode is activated. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

When verify is on, OS/2 performs a verify operation each time it does 
a file write to assure proper data recording on the disk. Although 
disl< recording errors are rare, this function has been provided for 
applications which may wish to verify the proper recording of critical 
data. 
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Purpose 

DosSleep suspends the current thread for a specified time, or If the 
requested Interval Is 0, gives up the remainder of the current time 
slice. 

Calling Sequence 

EXTRN DosSleep: FAR 

PUSH DWORD Timelnterval ; Interval size 
CALL DosSleep 

Where 

Timelnterval 

is the interval in milliseconds until the thread Is awakened. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Family API Considerations 

Some options operate differently in the DOS mode than they do in 
OS/2 mode. Therefore, the following restrictions apply to DosSleep 
when coding In the DOS mode : 

• DosSleep accuracy can be In error by 0.5%. 

• DosSleep can degrade system performance of non-foreground 
program operations when DOS mode Is In foreground. 

Remarks 

DosSleep suspends the current thread for the specified time period. 
The actual time it Is asleep may be off by a clock tick or two, 
depending on the execution status of the other threads running In the 
system. 

If the time is 0, then the thread foregoes the remainder of the current 
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time slice and allows any other ready threads of equal priority to run 
with the current thread for its next slice. Since the amount of sleep 
time specified Is 0, an immediate return with 0 delay is made if no 
other ready thread is found. 

If the time Is non-0, the time will be rounded up to the resolution of 
the scheduler clock. 

If DosSleep is used to regularly poll an external source to determine 
the occurrence of some event, a time equal the longest response 
interval should be used. 

For short time intervals the rounding-up process combined with the 
thread priority interactions may cause a sleeping interval to be longer 
than the requested time. Also, when a process completes sleeping, it 
is scheduled for execution. But that execution could be delayed by 
hardware interrupts or by another thread running at a higher priority. 
A program should not use the DosSleep call as a substitute for a real 
time clocl< because rounding of the sleep interval will cause cumula- 
tive errors. 

Note: For a time of 0, DosSleep will not yield to a thread of lower pri- 
ority. 
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Purpose 

DosStartSession provides an application program interface to start 
another session and specify the name of the program to start in the 
session. 

Calling Sequence 

EXTRN DosStartSession: FAR 

PUSH© OTHER StartData ;Start session data 

PUSH@ WORD SessID ;Session ID (returned) 

PUSH@ WORD PID ; Process ID (returned) 

CALL DosStartSession 

Where 

StartData 

Is a structure containing the data describing the session to be 
started. 



Size 


Description 


WORD 


Length 


WORD 


Related 


WORD 


FgBg 


WORD 


TraceOpt 


DWORD 


PgmTitle 


DWORD 


PgmName 


DWORD 


Pgm Inputs 


DWORD 


TermQ 



Length 

is the length of the data structure in bytes including Length itself. 
For OS/2, Length is 24 bytes. 

Related 

specifies whether the session created is related to the calling 
session. 

Value = 0 

new session is an independent session (not related) 
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Value = 1 

new session is a child session (related) 

An independent session is not a child session and cannot be con- 
trolled by the calling program. It cannot be specified as the target 
of DosSelectSession, DosSetSession, or DosStopSession. The 
TernnQ parameter is ignored for independent sessions, and the 
SessID and PID are not returned. 

The calling program (parent session) may specify a child session 
as the target of DosSelectSession, DosSetSession, and 
DosStopSession, for related sessions. The TermQ, SessID, and 
PID parameters are applicable when Related = 1 is specified. 
Note also that for related sessions, although a parent 
session/child session relationship is established, a parent 
process/child process relationship is not established. 

FgBg 

specifies whether the new session should be started in the fore- 
ground or bacl<ground. 

If value = 0 

start session in foreground. 
If value = 1 

start session in background. 

TraceOpt 

specifies whether the program started in the new session should 
be executed under conditions for tracing. 

• If value = 0, no trace. 

• If value = 1, trace. 

Pgm Title 

is the far address of an ASCIIZ string containing the program 
title. The string can be up to 31 bytes long including the termi- 
nating byte of 0. If the far address specified is 0, or if the ASCIIZ 
string is null, the initial title is PgmName minus any leading drive 
and path information. 

PgmName 

is the far address of an ASCIIZ string containing the fully-qualified 
drive, path, and filename of the program to be loaded. 
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Pgmlnputs 

is the far address of an ASCIIZ string containing the input argu- 
ments to be passed to the program. 

TermQ 

is an optional parameter. It is either 0 or the far address of an 
ASCilZ string containing the fully-qualified path and filename of an 
OS/2 queue. The OS/2 session manager writes a data element 
into the queue specified when the child session created as a 
result of this DosStartSession terminates. A parent session 
issues DosReadQueue to receive notification when a child session 
terminates. The request word returned by DosReadQueue is 0. 
The data element structure has the following format: 

Size Description 

WORD Session ID of child 
WORD Result code 

DosReadQueue is issued by the process that originally issued the 
DosStartSession request. This process is the only process that 
has addressability to the notification data element. The NoWait 
parameter on DosReadQueue must be set equal to zero. After 
reading and processing the data element, the caller frees the 
segment containing the data element using DosFreeSeg. 

SessID 

is the session ID associated with the created child session. 
SessID is returned only when the specified value for Related 
equals 1. The returned SessID is specified on subsequent calls to 
DosSelectSession, DosSetSession, and DosStopSession. 

P/D 

is the process ID associated with the created child process. PID is 
returned only when the value Related equal 1 is specified. The 
PID returned cannot be used on any OS/2 calls, (for example, 
DosSetPrty, which require a parent process/child process 
relationship). 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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Remarks 

New sessions can be started in the foreground only when the caller's 
session, or one of the caller's descendant sessions, is currently exe- 
cuting in the foreground. The new session appears in the Program 
Selector Switch list. 

Foregroundl Background Considerations: if FgBg = 0 is specified, 
and if neither the calling program nor any of its descendant sessions 
is executing in the foreground, the new session is started in the back- 
ground. A unique error code is also returned in AX in this case. 

Parent/Cliild Relationships: when Related = 1 is specified, 
DosStartSession establishes a parent session/child session relation- 
ship. A parent process/child process relationship is not established. 
The parent process is the shell process just as if the operator had 
started the program from the shell menu. A child program started 
through DosStartSession Is therefore not a descendant of the calling 
program and does not Inherit the calling process environment, open 
file handles, and other items passed to child processes through 
DosExecPgm. Furthermore, the RID returned by DosStartSession 
may not be used on any OS/2 calls, (for example, DosSetPrty) which 
require a parent process/child process relationship. Within any one 
session, DosStartSession, specifying Related = 1, may be issued by 
one and only one process. 

PgmName/Pgmlnputs Considerations: the program identified by 
PgmName is executed directly with no intermediate secondary 
command (CMD.EXE) process. Alternatively, the program can be 
executed indirectly through a secondary command (CMD.EXE) 
process by specifying CMD.EXE for PgmName and by specifying 
either /C or /K followed by the drive, path, and filename of the appli- 
cation to be loaded for Pgmlnputs. If the /C parameter is inserted at 
the beginning of the Pgmlnputs string, when the application program 
terminates, the session will terminate. If the /K parameter is inserted 
at the beginning of the Pgmlnputs string, when the application termi- 
nates, the operator will see the OS/2 command line prompt displayed. 
The operator can then either enter the name of another program or 
command to execute or enter the OS/2 EXIT command to terminate 
the session. 



2-256 



DosStartSession - 
Start Session 



When the PgmName far address is 0 or the ASCIIZ string is null, the 
program specified as a parameter to the shell on the ProtShell state- 
ment in the CONFIG.SYS file will be executed and passed the speci- 
fied Pgmlnputs. This is the OS/2 mode command processor 
(CMD.EXE) by default. 

The PgmName and Pgmlnputs ASCIIZ name strings combined length 
may not exceed 384 characters. 

ParentlChlld Termination Considerations: a parent session has only 
one termination queue. The parent creates the termination queue 
before it issues its first DosStartSession call that specifies the name 
of the queue. An application can use the termination queue for 
another purpose by passing a unique request parameter through the 
DosWriteQueue/DosReadQueue interface. Request parameter values 
0 through 99 are reserved for OS/2. Request parameter values 
greater than or equal to 100 are available for application use. 

If a parent session specifies the TermQ parameter on more than one 
DosStartSession call, the parameter is ignored on subsequent calls. 
Once a parent establishes a termination queue, the queue is posted 
when any child session terminates. The queue is posted regardless 
of who terminates the child session (for example, child, parent, or 
operator) and whether the termination is normal or abnormal. 

When a child session terminates, the result code returned in the 
TermQ data element will be the result code of the program specified 
by PgmName assuming either: 

1. the program is executed directly with no intermediate secondary 
command (CMD.EXE) process, or 

2. the program is executed indirectly through a secondary command 
(CMD.EXE) process and the /C parameter is specified. 

If the program is executed indirectly through a secondary command 
(CMD.EXE) process and the /K parameter is specified, the result code 
of the command process is returned. 

When a child session is running in the foreground at the time it termi- 
nates, the parent session becomes the foreground session. When a 
parent session terminates, any child sessions it created with 
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DosStartSession, specifying Related = 1, are terminated. When an 
independent session, created specifying Related = 0, is running in 
the foreground at the time it terminates, the shell chooses the next 
foreground session. 
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Purpose 

DosStopSession terminates a session previousiy started witli 
DosStartSession. 

Calling Sequence 

EXTRN DosStopSession: FAR 

PUSH WORD TargetOption ;Target option 

PUSH WORD SessID ;Session ID 

PUSH DWORD Reserved ; Reserved (must be zero) 

CALL DosStopSession 

Where 

TargetOption 

specifies whetlier tlie session specified by SessID or all sessions 
sliould be terminated. 

If value = 0 

terminate session specified. 
If value = 1 

terminate all child sessions and descendant sessions. 
SessID 

is tlie ID of the session to be terminated. The value specified for 
SessID must have been returned on a prior call to 
DosStartSession. SessID is ignored if TargetOption = 1. 

Reserved! 

is a DWORD of O's. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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Remarks 

DosStopSession may only be issued by a parent session for a child 
session. Neither the parent session itself nor any grandchild, and so 
forth, may be the target of this call. However, if the child session 
specified on DosStopSession does have descendants, these sessions 
will also be terminated. 

DosStopSession may only be used to terminate child sessions ori- 
ginally started by the caller with DosStartSesslon specifying Related 
= 1. That is, sessions started as independent sessions may not be 
stopped. 

If a child session is running in the foreground at the time it is stopped, 
the parent session becomes the foreground session. DosStopSession 
breaks any bond that existed between the parent session and the 
child session specified. 

A parent session may be running in either the foreground or back- 
ground when DosStopSession is issued. 

DosStopSession can only be issued by the process that originally 
started (using DosStartSesslon) the SessID specified. 

The process running in the session specified on the DosStopSession 
call may refuse to terminate. DosStopSession will return a normal 
return code in AX in this case. The only way to ensure that the target 
session has terminated is to wait upon notification through the termi- 
nation queue specified on DosStartSesslon. 
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Purpose 

DosSubAlloc allocates memory from a segment previously allocated 
by DosAllocSeg or DosAllocShrSeg and initialized by DosSubSet 

Calling Sequence 

EXTRN DosSubAlloc: FAR 

PUSH WORD SegSelector ; Segment selector 

PUSH@ WORD BlockOffset ; Block Offset (returned) 

PUSH WORD Size :S1ze of requested block 

CALL DosSubAl 1 oc 

Where 

SegSelector 

is the selector of the data segment from which the memory should 
be allocated. 

BlockOffset 

is where the offset to the block allocated is returned. 
Size 

is the size of the memory block requested in bytes. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

DosSubAlloc allocates a block of memory from a segment previously 
allocated by DosAllocSeg or DosAllocShrSeg and initialized by 
DosSubSet. 

Allocation size must be a multiple of four bytes. It will be rounded If 
not. The maximum value for the size parameter is the size of the 
segment allocated by DosAllocSeg or DosAllocShrSeg minus 8. Note 
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that no paragraph alignment is required; all requests are serviced on 
a byte alignment basis. 

The requestor must first call DosSubSet, after allocating the segment, 
and before attempting to call DosSubAlloc to allocate memory within 
the segment. Refer to "DosSubSet - Initialize or Set Allocated 
Memory" on page 2-264 for more information. 
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Purpose 

DosSubFree frees memory previously allocated by DosSubAlloc. 
Calling Sequence 

EXTRN DosSubFree: FAR 

PUSH WORD SegSelector : Segment selector 

PUSH WORD BlockOffset ;Offset of memory block to free 

PUSH WORD Size ;Size of block in bytes 

CALL DosSubFree 

Where 

SegSelector 

Is the selector of the data segment from which the memory should 
be freed. 

BlockOffset 

Is the offset of the memory block to be freed. The value specified 
must equal the BlockOffset returned on a previous DosSubAlloc 
call. 

Size 

is the size of the block to be freed In bytes. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

DosSubFree is used to free a block of memory that was allocated with 
DosSubAlloc. If the block specified overlaps unallocated memory, an 
error is generated. Like DosSubAlloc, the size parameter must be a 
multiple of four bytes, it will be rounded it not. 
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Purpose 

DosSubSet is used to initialize a segment for suballocation or to 
increase the size of a previously initialized, suballocated segment. 

Calling Sequence 

EXTRN DosSubSet: FAR 

PUSH WORD SegSelector ; Segment selector 

PUSH WORD Flags ; Parameter flags 

PUSH WORD Size ;S1ze of a block 

CALL DosSubSet 

Where 

SegSelector 

is the selector of the target data segment. 

Flags 

is set to 1 indicating initializing a segment, or to 0, indicating 
increasing the size of a segment already initialized. 

Size 

is the size of the segment in bytes. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

To initialize a segment, issue DosSubSet before issuing DosSubAlloc 
and set flags = 1. The segment must have been previously allocated 
with DosAllocSeg or DosAllocShrSeg. To increase the size of a 
segment, issue DosReallocSeg before issuing DosSubSet. Failure to 
issue DosSubSet after changing the size of a segment may yield 
unpredictable results. 
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The size parameter should be a multiple of four bytes, or it will be 
rounded. Note in DosSubSet, a size parameter of 0 indicates the 
segment is 64K, while in DosSubAlloc and DosSubFree, a size param- 
eter of 0 is an error. Other than this special case of 0 meaning 64KB, 
the minimum size which can be set is 12 bytes. 
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Purpose 

DosSuspendThread temporarily suspends thread execution until a 
DosResumeThread call is made for that thread ID. 

Calling Sequence 

EXTRN DosSuspendThread : FAR 

PUSH WORD ThreadlD ; Thread ID of thread to suspend 
CALL DosSuspendThread 

Where 
ThreadlD 

is the Thread ID of the thread to be suspended. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

The specified thread may not be suspended immediately because it 
may have some system resources locl<ed that should be freed first. 
However, the thread is not allowed to execute further application 
program instructions until a corresponding DosResumeThread is 
issued. 

A thread can only suspend threads within its process. 
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Start Asynchronous Time Delay 



Purpose 

DosTimerAsync starts a timer tiiat runs asynchronously to tlie thread 
issuing the request and clears a system semaphore when the speci- 
fied interval expires. 

Calling Sequence 

EXTRN DosTi merAsync : FAR 

PUSH DWORD Timelnterval ; Interval size 

PUSH DWORD SemHandle ; System semaphore handle 

PUSH© WORD Handle ;Timer handle (returned) 

CALL DosTimerAsync 

Where 

Timelnterval 

is the number of milliseconds (rounded up to the next clocl< ticl<) 
that passes before the semaphore is cleared. 

SemHandle 

is the handle of the system semaphore used to communicate the 
time out to the calling thread. This semaphore should be set by 
DosSemSet before DosTimerAsync is called. 

Handle 

is where the timer handle is returned. This handle may be passed 
to DosTimerStop to stop this timer before its time interval expires. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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Remarks 

DosTimerAsync is used to wait for a single asynchronous time. The 
thread waits for the timeout by issuing a DosSemWait. 

This function is the asynchronous analog of DosSleep. It allows a 
thread to start a timer while it is performing another task. This timer 
can be cancelled by calling the DosTimerStop function with the timer 
handle returned by DosTimerAsync. 

If another time out is needed, the semaphore is set and 
DosTimerAsync is reissued. To ensure reliable detection of the timer 
expiration, the system semaphore should be set prior to calling 
DosTimerAsync. 
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Start Periodic Interval Timer 



Purpose 

DosTimerStart starts a periodic interval timer that runs asyncliro- 
nously to the thread issuing the request. 

The semaphore is continually cleared at the specified time interval 
until the timer is turned off by DosTimerStop. 

Calling Sequence 

EXTRN DosTimerStart: FAR 

PUSH DWORD Timelnterval ; Interval size 

PUSH DWORD SemHandle ; System semaphore handle 

PUSH© WORD Handle ;Timer handle (returned) 

CALL DosTimerStart 

Where 

Timelnterval 

is the number of milliseconds (rounded up to the next clocic tick) 
that passes before the semaphore is cleared. 

SemHandle 

is the handle of the system semaphore used to communicate the 
time out to the calling thread. This semaphore should be set by 
DosSemSet before the next clear by the timer. 

Handle 

is where the timer handle Is returned. This handle may be passed 
to DosTimerStop to stop the periodic timer. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 



2-269 



DosTimerStart - 

Start Periodic Interval Timer 



Remarks 

DosTimerStart allows a timer to start and run asynchronously to a 
thread. A timer interval is cancelled by using the timer handle in the 
DosTimerStop call. This prevents the semaphore indicated in the 
DosTimerStart call from being sent notifications. 

The application detects the expirations of the timer when the 
semaphore is set prior to the next expiration of the timer. When an 
application waits for this semaphore to clear, more than one clearing 
of the timer may occur before the application resumes execution. If it 
is necessary to determine the actual elapsed time, the Global Infor- 
mation Segment milliseconds field can be saved prior to calling 
DosTimerStart. This saved value Is compared to the current value 
when the process resumes. See "DosGetlnfoSeg - Get Address of 
System Variables Segment" on page 2-83 for more Information 
regarding the Global Information Segment. 
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Purpose 

DosTimerStop stops a periodic interval timer started by 
DosTimerStart, or an asynchronous timer started by DosTimerAsync. 

Calling Sequence 

EXTRN DosTimerStop: FAR 

PUSH WORD Handle ; Handle of the timer 

CALL DosTimerStop 

Where 

Handle 

is the handle of the timer to be stopped. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

DosTimerStop is used to stop a periodic interval timer or asynchro- 
nous timer from running. No assumptions can be made about the 
state of the semaphore specified with DosTimerStart or 
DosTimerAsync. The application should put the semaphores into a 
known state. 
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Unlock Segment 



Purpose 

DosUnlockSeg unlocks a discardable segment. 
Calling Sequence 

EXTRN DosUnlockSeg: FAR 

PUSH WORD Selector ; Selector to unlock 
CALL DosUnlockSeg 

Where 

Selector 

Is the selector of the segment to be unlocked. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

This function is valid only on segments which have been allocated 
through DosAllocSeg with AllocFlags bit 2 (0100B) set. Note that it is 
an error to unlock a segment that Is already fully unlocked. 
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Purpose 

DosWrite transfers the specified number of bytes from a buffer to the 
specified fiie, synchronousiy with respect to the requesting process's 
execution. 



Calling Sequence 

EXTRN DosWrite: FAR 

PUSH WORD FlleHandle :F11e liandle 

PUSH© OTHER BufferArea ;User buffer 

PUSH WORD BufferLength ; Buffer length 

PUSH@ WORD BytesWritten ;Bytes written (returned) 

CALL DosWrite 



Where 

FileHandle 

is the fiie handie obtained from DosOpen. 

BufferAddress 

is the output buffer. 

BufferLength 

is the number of bytes to write. 

BytesWritten 

is where the number of bytes written is returned. 



Returns 

iF AX = 0 then NO error 
ELSE AX = error code 
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Family API Considerations 

Some options operate differently in ttie DOS mode tlian they do In 
OS/2 mode. Therefore, the following restriction applies to DosWrite 
when coding in the DOS mode : 

Use only single-byte DosWrites to COMx in PC/DOS. The COM 
device driver supplied with PC/DOS does not support multiple-byte 
I/O. 

Remarks 

Upon return from this function, BytesWrltten is the number of bytes 
actually written. If BytesWrltten is different from BufferLength this 
usually Indicates insufficient 6\sk space. 

A BufferLength value of 0 Is not considered an error. No data transfer 
will occur. There is no effect on the file or the file pointer. 

Buffers that are multiples in size of the hardware's base physical unit 
for data (the base physical unit is defined as the smallest block that 
can be physically written to the device) which are written to the file on 
these base boundaries, are written directly to the device. Other 
buffer sizes force some of the I/O to go through an internal system 
buffer and greatly reduce the efficiency of the I/O operation. 

The file pointer Is moved to the desired position by reading, writing, 
and performing function DosChgFllePtr (Move File Read/Write 
Pointer). 

if the file is read-only, the write to the file is not performed. 
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Purpose 

DosWriteAsync transfers the specified number of bytes to a fiie from 
a buffer, asynchronously with respect to the requesting process's 
execution. 



Calling Sequence 

EXTRN DosWriteAsync: FAR 



PUSH WORD 

PUSH@ DWORD 

PUSH@ WORD 

PUSH@ OTHER 

PUSH WORD 

PUSH@ WORD 



F1 1 eHandl e 

RamSemaphore 

ReturnCode 

BufferArea 

BufferLength 

BytesWritten 



File handle 

RAM semaphore 

I/O error RC (returned) 

User buffer 

Buffer length 

Bytes written (returned) 



CALL DosWriteAsync 



Where 

FileHandle 

Is the file handle obtained from DosOpen. 

RamSemaphore 

is used by the system to signal the caller that the write operation 
is complete. 

ReturnCode 

Is where the return code Is returned. 

BufterArea 

is the output buffer. 

BufferLength 

Is the number of bytes to be written. 

BytesWritten 

is where the number of bytes written is returned. 
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Returns 

AX = 0 

Note: When RamSemaphore is cleared and the read operation com- 
pletes, ReturnCode can be checked. 

Remarics 

When RamSemaphore is cleared, BytesWritten identifies the number 
of bytes written. If BytesWritten is different from BufferLength it 
usually Indicates insufficient disk space. 

A BufferLength value of 0 is not considered an error. No data transfer 
will occur. There is no effect on the file or the file pointer. 

RamSemaphore must be set by the application before the 
DosWriteAsync call is made. The application issues the following 
sequence: 

1. DosSemSet 

2. DosWriteAsync 

3. DosSemWait. 

Note: The program must not modify the contents of BufferArea or 
look at the values returned in ReturnCode or BytesWritten until after 
RamSemaphore is cleared. 

Buffers that are multiples in size of the hardware's base physical unit 
for data (the base physical unit is defined as the smallest block that 
can be physically written to the device) which are written to the file on 
these base boundaries will be written directly to the device. Other 
buffer sizes will force at least some of the I/O to go through an 
internal system buffer (if the File State indicates that internal buffers 
may be used) and reduce the efficiency of the I/O operation. 

The file read/write pointer can be moved to the desired position by 
reading, writing, or performing function DosChgFilePtr (Change File 
Read/Write Pointer). 
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The value of the file read/write pointer Is updated by the File Level 
Request Router before the I/O request is queued to the device driver. 

If the file is read-only, the write to the file is not performed. 
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Write to Queue 



Purpose 

DosWriteQueue adds an element to a queue. 



Calling Sequence 

EXTRN DosWriteQueue: FAR 



PUSH WORD 

PUSH WORD 

PUSH WORD 

PUSH@ OTHER 

PUSH WORD 



QueueHandle 
Request 
DataLength 
DataBuffer 
El emPri ori ty 



; Handle of queue to send to 
;Request identification data 
; Length of element being added 
; Element being added 
; Priority of element being added 



CALL DosWriteQueue 



Where 

QueueHandle 

is tlie handle of the queue to write to. 

Request 

Is a value to be passed with the queue element. This word is used 
for event encoding by the specific application. The data in this 
word is understood by the thread adding the element to the queue 
and by the thread which receives the queue element. There is no 
special meaning to this data and the operating system does not 
alter the data. 

DataLength 

is the length of the data being sent to the queue. 
DataBuffer 

is the buffer where the data, which is to be placed in the queue, is 
located. 

ElemPriorlty 

is the priority of the element being added to the queue. If the pri- 
ority is specified as 15, the element is added to the top of the 
queue, If the priority is specified as 0, the element is added as the 
last element in the queue. Elements with the same priority are in 
FIFO order. This parameter is valid for priority type queues only. 
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Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

DosWriteQueue adds entries to a specified queue. If the owning 
process closes a queue prior to this request being Issued, the 
QUEUE_DOES_NOT_EXIST, Invalid Queue Handle return code is 
returned. If the owning process invokes a system semaphore when 
DosReadQueue or DosPeekQueue are issued, other processes that 
issue DosWriteQueue for the used system semaphore must first issue 
DosOpenSem. 
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Chapter 3. OS/2 Keyboard Function Calls 

This chapter reflects the Keyboard API interface only. For informa- 
tion regarding the keyboard lOCtI Interface and keyboard monitor 
refer to the OS/2 Technical Reference Volume 1. 
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Read Character, Scan Code 



Purpose 

KbdCharIn returns a character data record from the keyboard. 
Calling Sequence 

EXTRN KbdCharIn: FAR 

PUSH© OTHER CharData -.Buffer for data 
PUSH WORD lOWait ; Indicate if wait 

PUSH WORD KbdHandle -.Keyboard handle 
CALL KbdCharIn 

Where 

CharData 

is a structure that contains the character data in the following 



WORD Shift State 
DWORD Time Stamp 

ASCII Character Code 

is derived from translation of the scan code received from 

the l<eyboard. 
Scan Code 

is code received from the Iceyboard identifying the key 
pressed. This scan code may have been modified during the 
translation process. 
Status 

indicates the state of the character: 



format: 



Size 

BYTE 
BYTE 
BYTE 
BYTE 



Description 

ASCII Character Code 

Scan Code 

Status 

NLS Shift Status 
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Bit Values 


Function 


Description 


Bit? = 0 


Bit 6 = 0 


undefined 


Bit? = 0 


Bit 6 = 1 


final character, interim cliaracter 
flag off 


Bit 7 = 1 


Bit 6 = 0 


interim character 


Bit ? = 1 


Bit 6 = 1 


final character, interim character 
flag on 


Bit 5 = 1 




On the spot conversion requested 


Bit 4 to 1 




reserved = 0 


BitO= 1 




shift status returned without char- 
acter 



NLS Shift Status 

Reserved = 0. 
Shift State 

is the state of the shift keys. The states are defined as 



follows: 


High 


Byte 


Bit# 


Meaning 


15 


SysReq Key Down 


14 


CapsLock Key Down 


13 


N urn Lock Key Down 


12 


Scroll Lock Key Down 


11 


Right Alt Key Down 


10 


Right Ctrl Key Down 


9 


Left Ait Key Down 


8 


Left Ctrl Key Down 


Low 


Byte 


Blt# 


Meaning 


? 


Insert ON 


6 


CapsLock ON 


5 


NumLock ON 


4 


Scroll Lock ON 


3 


Either Alt Key Down 
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2 Either Ctrl Key Down 
1 Left Shift Key Down 
0 Right Shift Key Down 
Time Stamp 

is the time stamp of the Wey strol<e that occupies a double 
word and is specified in milliseconds since iPL. 

lOWait 

indicates whether to wait if a character is not available. 
If value = 0 

the requestor will wait for a character if one is not available. 
If value = 1 

the requestor will get an immediate return if no character is 
available. 

KbdHandle 

identifies either the default keyboard or the logical keyboard. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Family API Considerations 

Some options operate differently in the DOS mode than they do in the 
OS/2 mode. Therefore, the following restrictions apply to KbdCharIn 
when coding in the DOS mode : 

• Interim Character is not supported 

• Status can be 0 or 401-1 

• KbdHandle is ignored. 

Remarks 

Extended ASCII codes return the first code as ODH or EOH in the char- 
acter field and the second code (extended code) in the scan code 
field. Usually the extended ASCII code is the scan code of the 
primary key that was pressed. 

Note: On an enhanced keyboard, the secondary enter key returns the 
normal character of ODh and a scan code of EOh. 
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Double-byte character codes (DBCS) require two function calls to 
obtain the entire code. 

If shift report is set with KbdSetStatus, then the CharData Record 
returned will reflect changed shift information only. 

KbdCharln completes when the handle has access to the physical 
keyboard (focus), or is equal to 0, and no other handle has the focus. 

The ASCII Character and Scan Code field of the CharData Structure 
are reserved and set to 0 when a shift state is received. 

A returned character is indicated by the final character flag, (bit 6 of 
the status byte), being set to 1. Bit 6 set to 0 indicates that no char- 
acter was returned. 

In general, if a thread can not continue until a character is received, it 
should use the KbdCharln function with the lOWait parameter set to 
wait for a character if one is not available. A thread in the foreground 
session that repeatedly polls the keyboard with KbdCharln (with no 
wait), can prevent all regular priority class threads from executing. If 
polling must be used and a minimal amount of other processing Is 
being performed, the thread should periodically yield the CPU by 
issuing a DosSleep for an interval of at least 5 milliseconds 
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Close a Logical Keyboard 



Purpose 

KbdClose ends the existing logicai Iceyboard identified by the icey- 
board handle. 

Calling Sequence 

EXTRN KbdClose: FAR 

PUSH WORD KbdHandle -.Keyboard handle 
CALL KbdClose 

Where 
KbdHandle 

identifies either the default keyboard or the logical keyboard. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

The close process results in a KbdFreeFocus and KbdFlushBuffer on 
the handle. A KbdClose of a 0 handle has no effect on the default key- 
board. 
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Deregister Keyboard Subsystem 



Purpose 

KbdDeRegister deregisters a keyboard subsystem previously regis- 
tered within a session. Only the process that issued the KbdRegister 
may issue KbdDeRegister. 

Calling Sequence 

EXTRN KbdDeRegister: FAR 
CALL KbdDeRegister 

Where 

None 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

None 
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Purpose 

KbdFlushBuffer clears the key stroke buffer. 
Calling Sequence 

EXTRN KbdFlushBuffer: FAR 

PUSH WORD KbdHandle -.Keyboard handle 
CALL KbdFlushBuffer 

Where 

KbdHandle 

identifies either the default keyboard or the logical keyboard. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Family API Considerations 

Some options operate differently in the DOS mode than they do in the 
OS/2 mode. Therefore, the following restriction applies to 
KbdFlushBuffer when coding in the DOS mode : 

• KbdHandle is ignored. 
Remarks 

KbdFlushBuffer completes when the handle has access to the phys- 
ical keyboard (focus), or is equal to 0 and no other handle has the 
focus. 
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Purpose 

KbdFreeFocus frees the logical to physical keyboard bond created by 
KbdGetFocus. 

Calling Sequence 

EXTRN KbdFreeFocus: FAR 

PUSH WORD KbdHandle -.Keyboard handle 
CALL KbdFreeFocus 

Where 

KbdHandle 

Identifies either the default keyboard or the logical keyboard. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

If other threads are waiting for this bond to end, then one of the 
waiting threads will be allowed to complete it KbdGetFocus upon 
completion of the KbdFreeFocus. If no threads are waiting for the a 
bond, then the physical keyboard reverts to the default keyboard. 

KbdFreeFocus may be replaced by issuing KbdRegister. Unlike other 
keyboard sub-system functions, the replaced KbdFreeFocus will be 
called only if there Is an outstanding focus. 
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Get Loaded Code Page IDs 



Purpose 

KbdGetCp allows a process to query the code page currently In use to 
translate scan codes to ASCII characters. 

Calling Sequence 

EXTRN KbdGetCp: FAR 

PUSH DWORD Reserved ; Reserved 
PUSHia WORD CodePagelD ;Code Page ID 
PUSH WORD KbdHandle : Keyboard handle 
CALL KbdGetCp 

Where 

Reserved 

Is reserved and set to 0. 

CodePagelD 

Is located in the application's data area. The keyboard support 
copies the current code page ID for a specified l^eyboard handle 
into this word. The code page ID is equivalent to one of the code 
page IDs specified in the CONFIG.SYS CODEPAGE = statement or 
0000. 

KbdHandle 

identifies either the default keyboard or the logical keyboard. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

KbdGetCp completes when the handle has access to the physical key- 
board (focus), or is equal to 0 and no other handle has the focus. 
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Purpose 

KbdGetFocus binds the logical keyboard to the physical keyboard. 
Calling Sequence 

EXTRN KbdGetFocus: FAR 

PUSH WORD lOWait ; Indicate if wait 

PUSH WORD KbdHandle : Keyboard handle 
CALL KbdGetFocus 

Where 
lOWalt 

indicates whether to wait if a character is not available. 

Bit# Meaning 

15-1 Reserved = 0 

0 indicates whether caller wants to wait for the bond. If 
value = 0, wait If value = 1, do not wait. 

KbdHandle 

identifies either the default keyboard or the logical keyboard. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

The keyboard handle identifies which logical keyboard to bind to. If 
the physical keyboard is not bound to a logical or default keyboard, 
then the bind proceeds immediately. The logical keyboard, identified 
by the handle, receives all further key strokes from the physical key- 
board. If the physical keyboard is already in use by a logical key- 
board, then the thread issuing KbdGetFocus waits until the bond can 
be made. Waiting threads do not execute In any definable order. 
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Get Keyboard Status 



Purpose 

KbdGetStatus gets the current state of the keyboard. 
Calling Sequence 

EXTRN KbdGetStatus: FAR 

PUSH@ OTHER Structure ;Data structure 
PUSH WORD KbdHandle ; Keyboard handle 
Call KbdGetStatus 

Where 

structure 

is a data structure that contains information used to set the Input 
Mode, Echo, Shift, Interim Character flags and the TurnAround 
character states to be assigned to the l<eyboard. The data struc- 
ture is defined as follows: 

Word 0 

is the length in bytes of the data structure including this 
word. High Byte is reserved and equal to 0. Low Byte is 
equal to 10. 
Word 1 

is a bit mask that represents functions whose state is to be 

altered by the current KbdSetStatus call. The bit mask is 

defined as follows: 

fift # Meaning 

15-09 = Reserved, set to 0 

08 = Shift Report ON 

07 = length of turnaround character 



0 = one byte, high byte only (ASCII) 



1 = two bytes (extended ASCII) (mean- 



06 
06 
04 
03 
02 



ingful only if bit 6 is on) 
= modify TurnAround character 
= modify Interim Character Flags 
= modify Shift State 
= ASCII mode ON 
= Binary mode ON 
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01 = Echo OFF 

00 = Echo ON 

If both bits 0 and 1 are OFF, the Echo state of the system is 
not altered. If both bits 2 and 3 are OFF, the BINARY/ASCII 
state of the system is not altered. If both bits 0 and 1 are ON 
or if both bits 2 and 3 are ON, the function will return an 
error. Echo is ignored if BINARY mode is set. 
Word 2 

Define TurnAround Character 

Character (ASCII, extended ASCII) defined as the Turn- 
around (Carriage Return) character. If the turnaround char- 
acter is just ASCII then it is defined in the low order byte. 
Words 

Interim Character Flags 



High Byte = NLS Shift State 
Low Byte = Status 

07 = Interim Character Flag ON 

06 = Reserved, set to 0 

05 = Program requested on-the-spot conversion 
04-00 = Reserved, set to 0 

Word 4 

The shift states are defined as follows: 
High Byte 

15 = SysReq Key Down 
14 = CapsLock Key Down 
13 = NumLock Key Down 
12 = Scroll Lock Key Down 
1 1 = Right Alt Key Down 
10 = Right Ctrl Key Down 
09 = Left Alt Key Down 

08 = Left Ctrl Key Down 
Low Byte 

07 = Insert ON 

06 = CapsLock ON 
05 = NumLock ON 
04 = ScrollLock ON 

03 = Either Alt Key Down 
02 = Either Ctrl Key Down 
01 = Left Shift Key Down 
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00 = Right Shift Key Down 
KbdHandle 

is the handle of the KBD resource. OS/2 requires this value 
always be a reserved word of Os. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Family API Considerations 

Some options operate differently in the DOS mode than they do in the 
OS/2 mode. Therefore, the following restrictions apply to 
KbdGetStatus when coding in the DOS mode : 

• Interim Character is not supported 

• Turnaround character is not supported 

• NLS Shift State will always be null 

• KbdHandle is ignored. 

Remarks 

The initial state of the keyboard is established by the system at appli- 
cation load time. Some default states may be modified by the appli- 
cation through KbdSetStatus. KbdGetStatus will return only those 
Icey board parameters initially set by KbdSetStatus. The returned 
parameters are: 

• Input Mode 

• interim Character Flags 

• Shift State 

• Echo State 

• Turnaround Character 

KbdGetStatus completes only when the handle has access to the 
physical i^eyboard (focus) or the handle is 0 and no other handle has 
the focus. 
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Purpose 

KbdOpen creates a new logical keyboard. 
Calling Sequence 

EXTRN KbdOpen: FAR 

PUSH@ WORD KbdHandle ; Keyboard handle 

CALL KbdOpen 

Where 
KbdHandle 

Identifies either the default keyboard or the logical keyboard. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

A keyboard handle is returned by KbdOpen identifying a new logical 
keyboard. KbdOpen initializes the logical keyboard to the system 
default CodePage. 
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Peek at Character, Scan Code 



Purpose 

KbdPeek returns the character data record, if available, from the key- 
board without removing it from the buffer. 

Calling Sequence 

EXTRN KbdPeek: FAR 

PUSH@ OTHER CharData ; Buffer for data 

PUSH WORD KbdHandle ; Keyboard handle 
CALL KbdPeek 

Where 

CharData 

Is a structure that contains the character data in the following 



format: 




Size 


Description 


BYTE 


ASCII Character Code 


BYTE 


Scan Code 


BYTE 


Status 


BYTE 


NLS Shift Status 


WORD 


Shift State 


DWORD 


Time Stamp 



ASCII Character Code 

is an ASCII character derived from translation of the scan code 
received from the keyboard. 

Scan Code 

is code received from the keyboard identifying the key pressed. 
This scan may have been modified during the translation process. 

Status 

indicates the state of the character: 
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Bit Values 


Function 


Description 


Bit 7 = 0 


Bit 6 = 0 


undefined 


Bit 7 = 0 


Bit 6 = 1 


final character, interim character 
flag off 


Bit 7 = 1 


Bit6 = 0 


interim character 


Bit 7 = 1 


Bite = 1 


final character, interim character 
flag on 


Bit 5 = 1 




On the spot conversion requested 


Bit 4 to 1 




reserved = 0 


BitO= 1 




shift status returned without char- 
acter 



NLS Shift Status 
Reserved = 0. 

Shift State 

Is the state of the shift keys. The states are defined as follows: 



Bll# 


Meaning 


15 


SysReq Key Down 


14 


CapsLock Key Down 


13 


NumLock Key Down 


12 


Scroll Lock Key Down 


11 


Right Alt Key Down 


10 


Right Ctrl Key Down 


09 


Left Alt Key Down 


08 


Left Ctrl Key Down 


07 


Insert ON 


06 


CapsLock ON 


05 


NumLock ON 


04 


ScrollLock ON 


03 


Either Alt Key Down 


02 


Either Ctrl Key Down 


01 


Left Shift Key Down 


00 


Right Shift Key Down 
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Time Stamp 

is the time stamp of the key stroke occupying a double word and 
specified in milliseconds. 

KbdHandle 

identifies either the default keyboard or the logical keyboard. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Family API Considerations 

Some options operate differently in the DOS mode than they do in the 
OS/2 mode. Therefore, the following restrictions apply to KbdPeek 
when coding for the DOS mode: 

• Interim character is not supported 

• Status = 0 or 40H 

• KbdHandle is ignored. 

Remarks 

Extended ASCII codes return the first code as ODh or EOH in the char- 
acter field and the second code (extended code) in the scan code 
field. Usually the extended ASCII code is the scan code of the 
primary key that was pressed. 

Note: On an enhanced keyboard, the secondary enter key returns the 
normal character of ODh and a scan code of EOh. 

Double-byte character codes (DBCS) require two function calls to 
obtain the entire code. 

If shift report is set by KbdSetStatus then the CharData Record 
returned reflects only the changed shift information. 

The ASCII Character and Scan Code, field of the CharData Structure 
are reserved and set to 0 when a shift state is received. 
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A returned character is indicated by the final character flag, (bit 6 of 
the status byte), being set to 1. Bit 6 set to 0 indicates that no char- 
acter was returned. 

KbdPeek completes when the handle has access to the physical key- 
board (focus) or is equal to 0 and no other handle has the focus. 

In general, if a thread can not continue until a character is received, it 
should use the KbdCharIn function with the lOWait parameter set to 
wait for a character if one is not available. A thread in the foreground 
session that repeatedly polls the keyboard with KbdPeek (with no 
wait), can prevent all regular priority class threads from executing. If 
polling must be used and a minimal amount of other processing is 
being performed, the thread should periodically yield the CPU by 
issuing a DosSleep for an interval of at least 5 milliseconds. 
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Register Keyboard Subsystem 



Purpose 

KbdRegister registers a keyboard subsystem within a session. 
Calling Sequence 

EXTRN KbdRegister: FAR 

PUSH(a ASCIIZ ModuleName -.Module name 

PUSm ASCIIZ EntryPoint -.Entry point name 

PUSH DWORD FunctionMask ; Function mask 

CALL KbdRegister 

Where 

ModuleName 

contains the dynamic linl< moduie name. Maximum length is 129 
bytes (including ASCIIZ terminator). 

EntryPoint 

contains the dynamic rml< entry point name of a routine which will 
receive control when any of the registered functions are called. 
Maximum length is 33 bytes (including ASCIIZ terminator). 

FunctionMask 

is a bit mask where each bit identifies a keyboard function being 
registered. The bits are defined as follows: 
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Bit# 


Funttion 


31-14 


Reserved = 0 


13 


KbdSetCustXt 


12 


KbdXIate 


11 


KbdSetCp 


10 


KbdQetCp 


9 


KbdFreeFocus 


8 


KbdGetFocus 


7 


KbdClose 


g 


KbdOoen 


5 


KbdStringIn 


4 


KbdSetStatus 


3 


KbdGetStatus 


2 


KbdFlushBuffer 


1 


KbdPeek 


0 


KbdCharIn 



Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

The Base Keyboard Subsystem is the keyboard subsystem default. 
There can be only one KbdRegister call outstanding at a time without 
an intervening KbdDeRegister. KbdDeRegister must be issued by the 
same process that Issued the KbdRegister. 

When any registered function is called, control is routed to 
EntryPoint. When this routine is entered, four additional values are 
pushed onto the stack. The first is the index number (WORD) of the 
routine being called. The second is a near pointer (WORD). The third 
is the caller's DS register (WORD). The fourth is the return address 
(DWORD) to the keyboard router. For example, if KbdFlushBuffer 
were a registered function and if KbdFlushBuffer were called and 
control routed to EntryPoint, the stack would appear as if the fol- 
lowing instruction sequence were executed: 
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PUSH 


WORD 


KbdHandl e 


CALL 


FAR 


KbdFlushBuffer 


PUSH 


WORD 


Index 


CALL 


NEAR 


Entry point in Kbd router 


PUSH 


DS 




CALL 


FAR 


Dynamic link entry point 



The index numbers that correspond to the registered functions are 
listed below: 



00 KbdCharIn 

01 KbdPeek 

02 KbdFlushBuffer 

03 KbdGetStatus 

04 KbdSetStatus 

05 KbdStringIn 

06 KbdOpen 



07 KbdClose 

08 KbdGetFocus 

09 KbdFreeFocus 

10 KbdGetCp 

11 KbdSetCp 

12 KbdXIate 

13 KbdSetCustXt 



When a registered function returns to the keyboard router, the con- 
tents of AX are interpreted as follows: 

AX = 0 

no error. Do not invoke the corresponding Base Keyboard Sub- 
system. Return AX = 0 to the caller. 
AX = -1 

invoke the corresponding Base Keyboard Subsystem. Return AX 
= return code from the Base Keyboard Subsystem. 
AX = error, (not 0 or -1) 

do not invoke the corresponding Base Keyboard Subsystem. 
Return AX = error to the caller. 



Within a session, a KbdRegister call remains in effect until a 
KbdDeRegister is issued or the session ends. KbdDeRegister must 
be called by the same process that issued KbdRegister. 
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Purpose 

KbdSetCp allows the process to set the code page used to translate 
key strokes received from the keyboard. 

Calling Sequence 

EXTRN KbdSetCp: FAR 

PUSH WORD Reserved 

PUSH WORD CodePagelD 

PUSH WORD KbdHandle 

CALL KbdSetCp 

Where 

Reserved 

is a reserved word equal to 0. 

CodePagelD 

is a word in the application's data area. It represents a code page 
id. The code page ID word must be equivalent to one of the code 
page IDs specified on the CONFIG.SYS CODEPAGE = statement 
or 0000. If the code page ID does not match one of the ids on the 
CODEPAGE = statement, an error will result. The code page 
word currently must have one of the following code page 



identifiers: 




Identifier 


Description 


0000 


Resident code page 


0437 


IBM PC US 0437 


0850 


Multilingual 


0860 


Portuguese 


0863 


Canadian-French 


0865 


Nordic 


KbdHandle 





identifies either the default keyboard or the logical keyboard. 



; Reserved 
;code page ID 
; Keyboard handle 
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Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

The code page specified must be 0000 or have been specified on the 
CONFiG.SYS CODEPAGE = statement. Value = 0000 Indicates to use 
the device driver's built in code page. 

To clear l<ey strolces translated with the previous code page, the 
buffer is flushed when the code page switch completes. 

KbdSetCp completes when the handle has access to the physical key- 
board (focus), or is equal to 0 and no other handle has the focus. 
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Purpose 

KbdSetCustXt installs on the specified handle the code page pointed 
to in this call. This code page will affect only this handle. 

Calling Sequence 

EXTRN KbdSetCustXt: FAR 

PUSH© OTHER CodePagelD ;Translation Table 
PUSH WORD KbdHandle -.Keyboard handle 
CALL KbdSetCustXt 

Where 
CodePagelD 

is a translation table used to translate scan code to ASCII code for 
a specified handle. The format of the code page is documented in 
the Set Code Page lOCtI 50H. (Refer to Chapter 3 in this bool< for a 
complete discussion of Set Code Page lOCtI 50H). 

KbdHandle 

identifies either the default keyboard or the logical Iteyboard. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

The code page must be maintained in the callers memory. No copy 
of the code page is made by KbdSetCustXt. 

Note: KbdSetCp reverses the action of KbdSetCustXt and sets the 
handle equal to one of the system code pages. If memory is dynam- 
ically allocated by the caller for the code page and is freed before the 
KbdSetCp is performed, KbdSetCp and future translations may fail. 

KbdSetCustXt completes when the handle has access to the physical 
keyboard (focus), or is equal to 0 and no other handle has the focus. 
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Set Foreground Keyboard Priority 



Purpose 

KbdSetFgnd raises the priority of tlie foreground Iceyboard's tliread. 
Calling Sequence 

EXTRN KbdSetFgnd: FAR 
CALL KbdSetFgnd 

Where 

None 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

Note: KbdSetFgnd is used by a subsystem, not an application. 
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Purpose 

KbdSetStatus sets the characteristics of the Iceyboard. 
Calling Sequence 

EXTRN KbdSetStatus: FAR 

PUSH© OTHER Structure ;Data structure 
PUSH WORD KbdHandle -.Keyboard Handle 
Call KbdSetStatus 

Where 

structure 

is a data structure that contains information to set the Input Mode, 
Echo, Shift, Interim Character Flags and the TurnAround Char- 
acter States to be assigned to the keyboard. The data structure is 
defined as follows: 

WordO 

is the length in bytes of the data structure including this word High 
Byte is reserved and equal to 0. Low Byte is equal to 10. 

Word1 

is a bit masl< that represents functions whose state is to be altered 
by the current KbdSetStatus call. The bit mask is defined as 
follows: 

Bit # Meartiitg 

15-09 = Reserved, set to 0 

08 = Shift Report ON 

07 = length of turnaround character 

0 = one byte, high byte only (ASCII) 

1 = two bytes (extended ASCII) (meaningful only 
if bit six is on) 

06 = TurnAround character is to be modified 

05 = Interim Character Flags are to be modified 

04 = Shift state Is to be modified 

03 = ASCII mode ON 

02 = Binary mode ON 
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01 = Echo OFF 
00 = Echo ON 

If both bits 0 and 1 are OFF, the Echo state of the system is not 
altered. If both bits 2 and 3 are OFF, the BINARY/ASCII state of 
the system is not altered. If both bits 0 and 1 are ON or if both bits 

2 and 3 are ON, the function will return an error. Echo is ignored if 
BINARY mode is set. 

Word 2 

Define TurnAround Character 

Character (ASCII, extended ASCII) defined as the Turnaround 
(Carriage Return) character. If the turnaround character is just 
ASCII then it is defined in the low order byte. 

Word 3 

Interim Character Flags 

High Byte = NLS Shift State 

Low Byte = Status 

07 = Interim Character Flag ON 

06 = Reserved, set to 0 

05 = Program requested on-the-spot conversion 

04-00 = Reserved, set to 0 

Word 4 

Shift State 

The shift states are defined as follows: 



15 


= SysReq Key Down 


14 


= CapsLock Key Down 


13 


= N urn Lock Key Down 


12 


= Scroll Lock Key Down 


11 


= Right Alt Key Down 


10 


= Right Ctrl Key Down 


09 


= Left Alt Key Down 


08 


= Left Ctrl Key Down 


07 


= Insert ON 


06 


= CapsLock ON 


05 


= NumLock ON 


04 


= Scroll Lock ON 


03 


= Either Alt Key Down 
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02 = Either Ctrl Key Down 
01 = Left Shift Key Down 
00 = Right Shift Key Down 

KbdHandle 

identifies either the default Iteyboard or the logical Iceyboard. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Family API Considerations 

Some options operate differently in the DOS nnode than they do in the 
OS/2 mode. Therefore, the following restrictions apply to 
KbdSetStatus when coding in the DOS mode : 

• RAW Mode, and ECHO ON is not supported and will return an 
error if requested 

• KbdHandle is ignored 

• Interim character is not supported 

• Turnaround character is not supported. 

Remarlcs 

KbdSetStatus completes when the handle has access to the physical 
keyboard (focus), or is equal to 0 and no other handle has the focus. 

Note: Shift report is not valid in ASCII mode. 

When turning off shift report the application must realize that there 
may be remaining shift report CharDataRecords to be read. If the 
application does not want to process these it should do a 
KbdFlushBuffer after turning off the shift report function. 
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Purpose 

KbdStringln reads a character string (cliaracter codes only) from the 
keyboard. 

Calling Sequence 

EXTRN KbdStringln: FAR 

PUSH@ OTHER CharBuffer 

PUSH© OTHER Length 

PUSH WORD lOWait 

PUSH WORD KbdHandle 

CALL KbdStringln 

Wliere 

CharBuffer 

is the buffer for the character string. 

Length 

is the length of the character string buffer. On entry Length is the 
maximum number of bytes in the buffer. The maximum Length 
can be specified is 255 bytes. 

Length is defined by the following structure: 

Size Description 

WORD Input Buffer Length 
WORD Received Input Length 

Note: Template processing has meaning only in the ASCII mode 
of operation. 

lOWalt 

indicates whether to wait if a character is not available. 
0 = Walt 

In BINARY input mode, the requestor waits until CharBuffer is 
full. In ASCII input mode, the requestor waits until a carriage 
return is struck. 



;Char string buffer 
: Length table 

; Indicate if wait for char 
; Keyboard handle 
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1 s No Wait 

The requestor gets an immediate return if no characters are 
available. If characters are available, KbdStringIn returns 
immediately with as many characters as are available (up to 
the maximum). No Wait is not supported for ASCII input mode. 

KbdHandle 

identifies either the default keyboard or the logical keyboard. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Family API Considerations 

Some options operate differently in the DOS mode than they do in the 
OS/2 mode. Therefore, the following restrictions apply to KbdStringIn 
when coding in the DOS mode : 

• KbdHandle is ignored. 

• ECHO state must always be set ON. 

See also "DosRead - Read from File" on page 2-191 for the differ- 
ences between coding in OS/2 mode and DOS mode when reading 
from a handle opened to the device "CON." 

Remarks 

The character strings may be optionally echoed on the display if echo 
mode is set. When echo is on each character is echoed as it is read 
from the keyboard. Echo mode and BINARY mode are mutually 
exclusive. Reference KbdSetStatus and KbdGetStatus for more infor- 
mation. 

In ASCII mode, 2-byte character codes only return in complete form. 
An extended ASCII code is returned in a 2-byte string. The first byte 
is ODh or EON and the next byte is an extended code. 

In input mode (BINARY, ASCII), The following returns can be set and 
retrieved via KbdSetStatus and KbdGetStatus: 
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Turnaround Character 
Echo Mode 

Interim Character Flag 
Shift State 

The default input mode is ASCII. 



The received input length is also used by the KbdStringIn line edit 
functions for re-displaying and entering a caller specified string. On 
the next KbdStringIn call the received input length indicates the 
length of the input buffer that may be recalled by the user using the 
line editing keys. A value of 0 inhibits the line editing function for the 
current KbdStringIn request. 

KbdStringIn completes when the handle has access to the physical 
[keyboard (focus), or is equal to 0 and no other handle has the focus. 
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Purpose 

KbdSynch synchronizes access for a keyboard subsystem to the key- 
board device driver. 

Calling Sequence 

EXTRN KbdSynch: FAR 

PUSH WORD lOWait ; Indicate if wait 

CALL KbdSynch 

Where 
lOWait 

indicates whether to wait if a character is not avaiiable. 

Bit # Meaning 

15-01 Reserved = 0 

0 Indicates whether requestor waits for access to the 

device driver, if bit = 1, wait, if bit = 0, do not wait. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

KbdSynch requests an exclusive system semaphore. See 
"DosCloseSem - Close System Semaphore" on page 2-19 for 
more information regarding system semaphores. This semaphore 
request clears when the subsystem returns to the keyboard router. 
KbdSynch blocks all other threads within a session until the 
semaphore clears (returns from the subsystem to the router). To 
ensure proper synchronization, KbdSynch should be issued by a key- 
board subsystem if it intends to issue DosDevlOCtI or access dynam- 
ically modifiable per-session shared data. KbdSynch will not protect 
globally shared data from threads in other sessions. 
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Purpose 

KbdXIate translates scan code and shift states Into ASCII code. 
Calling Sequence 

EXTRN KbdXIate: FAR 

PUSH@ OTHER XlateRecord jTranslation Record 

PUSH WORD KbdHandle ; Keyboard handle 
CALL KbdXIate 

Where 
X/afeAecord 

is a structure that contains the translation record in the following 
format: 



Function 


Value 




CharData 
Record 


as defined in KbdCharIn 


10 

BYTES 


KbdDDFIags 


as defined for Monitor packets 


WORD 


XI ate Flags 


defined below 


WORD 


XIate State 1 


defined below 


WORD 


XIate State 2 


defined below 


WORD 



XIate Flags 

High Byte 

Bits 8-15, Reserved = 0 

Low Byte 

Bits 1-7, Reserved = 0 

Bit 0 = Translation complete 
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X/ate State 1 and XIate State 2 

identifies the state of translation across successive calls. Initially 
these words should be 0. They should be reset to 0 to start a new 
translation. 

Note: It may take several calls to this lOCtI to complete a char- 
acter. These field should not be revised unless fresh start to 
translation is desired. 

KbdHandle 

identifies either the default keyboard or the logical keyboard. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

The desired shift state to use for translation is located in the 
CharDataRecord. 

KbdXIate completes when the handle has access to the physical key- 
board (focus), or is equal to 0 and no other handle has the focus. 

Note: It may take several calls to complete a translation due to 
accent key combinations, etc. 
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Chapter 4. OS/2 Mouse Function Calls 

For information regarding mouse device drivers, mouse pointer draw 
device, mouse installation and mouse lOCtIs, refer to the OS/2 Tech- 
nical Reference, Volume 1 
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Purpose 

MouClose closes the mouse device for the current session. 
Calling Sequence 

EXTRN MouClose: FAR 

PUSH WORD DeviceHandle ;Mouse device handle 
CALL MouClose 

Where 

DeWceHand/e 

Is the handle of the mouse device obtained from a previous 
MouOpen. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

MouClose closes the mouse device for the current session and 
removes the mouse device driver handle from the list of valid open 
mouse device handles. 
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Purpose 

MouDeRegister deregisters a mouse subsystem previously registered 
witliin a session. 

Calling Sequence 

EXTRN MouDeRegister: FAR 
CALL MouDeRegister 

Where 

No parameters are passed. 
Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

MouDeRegister causes mouse calls for the session to revert to the 
Base Mouse Subsystem 

Processes issuing MouDeRegister calls must conform to the following 
rules: 

• The process which issued the MouRegister must release the 
session (by a MouDeRegister), from the registered subsystem 
before another PID may issue MouRegister. 

• The process which issued the MouRegister is the only process 
which may issue MouDeRegister against the currently registered 
subsystem. 

• Once the owning process has released the subsystem with a 
MouDeRegister, any other process in the session may issue a 
MouRegister and therefore modify the mouse support for the 
entire session. 
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Purpose 

MouDrawPtr allows a process to notify the mouse device driver tliat 
an area previously restricted to the pointer image is now available to 
the mouse device driver. 

Calling Sequence 

EXTRN MouDrawPtr: FAR 

PUSH WORD DevlceHandle ;Mouse device handle 
CALL MouDrawPtr 

Where 

DeviceHandle 

is the handle of the mouse device obtained from a previous 
MouOpen. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

The collision area (the pointer image restricted area) is established 
by MouOpen and by MouRemovePtr. MouDrawPtr nullifies the colli- 
sion area. If there was no collision area at the time the MouDrawPtr 
was called, the MouDrawPtr is a null operation. 

immediately after MouOpen is issued, the collision area is defined as 
the size of the display. A MouDrawPtr can be issued to begin pointer 
drawing after the MouOpen. 
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Purpose 

MouFlushQue directs the mouse driver to flush (empty) the mouse 
event queue for the session. 

Calling Sequence 

EXTRN MouF1usliQue:FAR 

PUSH WORD DeviceHandle :Mouse device handle 
CALL MouFlushQue 

Where 
DeviceHandle 

is the handle of the mouse device obtained from a previous 
MouOpen. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

MouFlushQue is implemented via the Generic lOCtI, Category OBH, 
option 01 H "flush input buffer" call. 
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Purpose 

Returns status flags for the mouse device driver currently installed. 
Calling Sequence 

EXTRN MouGetDevStatus:FAR 

PUSH@ WORD DeviceStatus :Current status flags 

PUSH WORD DevlceHandle ; Mouse device handle 

CALL MouGetDevStatus 

Where 

DeviceStatus 

is where the current status flag settings are returned to the appli- 
cation for the currently installed mouse device driver. 

The return value is a 2-byte set of bit flags. 

High Byte: 



Bit # Meaning 

07-02 -Reserved = 0 

01 -set if mouse data returned in micl(eys, not display 
units 

00 -set if the interrupt level pointer draw routine is not 
called 

Low Byte: 

Bit # Meaning 

07-04 -Reserved = 0 

03 -set if pointer draw routine disabled by unsupported 

mode 

02 -set if flush in progress 

01 -set if block read in progress 

00 -set if event queue busy with I/O 



DeWceHancf/e 

is the handle of the mouse device obtained from a previous 
MouOpen. 
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Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

None 
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Purpose 

MouGetEventMask returns the current value of the mouse event 
queue mask. 

Calling Sequence 

EXTRN MouGetEventMas k : FAR 

PUSH@ WORD EventMask ; Event Mask word 
PUSH WORD Dev1ceHand1e ;Mouse device handle 
CALL MouGetEventMask 

Where 

EventMask 

is where the current mouse device drivers event mask is returned 
to the caller by the mouse device driver. 

The EventMask is set by MouSetEventMask, and has the following 
definition: 



Bit No. Meaning 

07-15 - Reserved = 0 

06 - set to receive button 3 press/ release events 

05 - set to receive button 3 press/release events, with 

mouse motion 

04 - set to receive button 2 press/release events 

03 - set to receive button 2 press/release events, with 

mouse motion 

02 - set to receive button 1 press/release events 

01 - set to receive button 1 press/release events, with 

mouse motion 

00 - set to receive mouse motion events with no button 

press/ release events. 



DeWceHancf/e 

contains the handle of the mouse device obtained from a previous 
MouOpen. 
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Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

Note: Buttons are logically numbered from left to right. 
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Purpose 

MouGetNumButtons returns the number of buttons supported on the 
mouse driver currently installed. 

Calling Sequence 

EXTRN MouGetNumButtons: FAR 

PUSH@ WORD NumberOf Buttons ; Number of mouse buttons 

PUSH WORD DeviceHandle :Mouse device handle 

CALL MouGetNumButtons 

Where 

NumberOfButtons 

is where the number of physical buttons on the mouse is returned. 

DeviceHandle 

contains the handle of the mouse device obtained from a previous 
MouOpen. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

The return values for the number of buttons supported are: 

1 = One mouse button 

2 = Two mouse buttons 

3 = Three mouse buttons 
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Purpose 

MouGetNumMickeys returns the number of mickeys per centimeter 
for the mouse driver currently installed. 

Calling Sequence 

EXTRN MouGetNumMickeys: FAR 

PUSH@ WORD NumberOf Mickeys ;Number mickeys/centimeter 

PUSH WORD DeviceHandle ;Mouse device handle 

CALL MouGetNumMickeys 

Where 

NumberOIMIckeys 

is where the number of mickeys (mouse movement units) per cen- 
timeter of screen height or width are returned by the mouse 
support. 

DeviceHandle 

contains the handle of the mouse device obtained from a previous 
MouOpen. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

The return value is dependent on the mouse and its current setting. 
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Purpose 

MouGetNumQueEl returns the current status for the mouse device 
driver event queue. 

Calling Sequence 

EXTRN MouGetNumQueEl: FAR 

PUSH@ OTHER QueDataRecord ;Ptr to 2-worcl structure 

PUSH WORD Devi ceHandl e :Mouse device handle 

CALL MouGetNumQueEl 

Where 

QueDataRecord 

is a structure in application storage where queue status is 
returned. This structure receives 2 full word parameters as 
follows: 

Word 0 = 

the current number of event queue elements. The number of 
queue elements value Is in the range of 0 <= value <= 
MaxNumQueElements. 
Word 1 = 

the mouse configured MaxNumQueElements value. 
DeWceffand/e 

contains the handle of the mouse device obtained from a previous 
MouOpen. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

The MaxNumQueElements returned by this function is established 
during mouse device driver configuration. See DEVICE=MOUSExxx 
in the IBM Operating System/2 User Reference. 
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Purpose 

MouGetPtrPos queries the mouse driver to determine tlie current row 
and coiumn coordinate position of tlie mouse pointer sliape. 

Calling Sequence 

EXTRN MouGetPtrPos: FAR 

PUSH© OTHER PtrPos ;Double word structure 

PUSH WORD DeviceHandle -.Mouse device handle 

CALL MouGetPtrPos 

Where 
PtrPos 

is a structure in application storage wliere position Information is 
returned. The structure format of the returned position informa- 
tion is defined as follows: 

• Word 0 = current pointer row coordinate screen position. 

• Word 1 = current pointer column coordinate screen position. 

Both parameters are in either pixel or character units, depending 
on the mode of the display for that session. 

Coordinate positions are relative to physical displacement from 
the top left corner of the display screen. 

DeWceHand/e 

contains the handle of the mouse device obtained from a previous 
MouOpen. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

None 
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Purpose 

MouGetPtrShape allows a process to get (copy) the pointer shape for 
the session. 



Calling Sequence 

EXTRN MouGetPtrShape: FAR 

PUSH@ OTHER PtrBuffer 

PUSH@ OTHER PtrDefRec 

PUSH WORD DevlceHandle 

CALL MouGetPtrShape 



; Pointer shape buffer 

: Pointer definition structure 

;Mouse device handle 



Where 

PtrBuffer 

is an area in application storage where the pointer draw device 
driver returns the pointer bit image. 

PtrDefRec 

is a structure in application storage where the application stores 
the necessary data for the pointer draw device driver to build a 
Row by Col image for each bit plane for the currently running 
display mode. 

The pointer definition record structure is described below: 

Word 0 = TotLength 
Word 1 = Col 
Word 2 = Row 
Word 3 = ColOffset 
Word 4 = RowOffset 

TotLength 

contains the total length in bytes necessary for the pointer 
draw device driver to build a Row by Column image for each 
bit plane for the currently running display mode. The length of 
the pointer buffer is supplied by the calling application. The 
actual length of the pointer image is always returned in this 
word. If the total length of the pointer buffer supplied by the 
application is not large enough to hold the pointer image, an 
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error is returned. In this case, the caller can use the value 
returned in TotLength to determine the buffer size needed. 

Note: See "MouSetPtrShape - Set Mouse Pointer Shape" 
on page 4-38 for the calculations necessary to determine the 
size. 

Col 

is a full word returned by pointer draw device driver: 
For graphics modes: 

it contains the pixel width (cols) of the mouse shape for the 

session. 
For text modes: 

will be equal to 1. 

Row 

is a full word returned by the pointer draw device driver: 
For graphics modes: 

pixel height (row) of the mouse shape for the session. Must 

be greater than or equal to 1. 
For text modes: 

row must be equal to 1. 
ColOffset 

is returned by the pointer draw device to indicate the relative 
column pixel offset for the pointer image used for coordinate 
tracking. This defines the column coordinate for the pointer 
image hotspot. This value is a signed number that represents 
character or pixel offset, depending on the display mode. 
RowOffset 

is returned by the pointer draw device to indicate the relative 
row pixel offset for the pointer image used for coordinate 
tracking. This defines the row coordinate for the pointer image 
hotspot. This value is a signed number that represents char- 
acter or pixel offset, depending on the display mode. 

Note: For text modes, row and column offset will equal 0. 

DeWceHancf/e 

contains the handle of the mouse device obtained from a previous 
MouOpen. 
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Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

The application passes a parameter list with the same meaning as 
defined for MouSetPtrShape, to the mouse device driver. The mouse 
device driver copies the parameters that describe the pointer shape 
and attributes into the pointer definition control block pointed to by 
the PtrDefRec parameter. The word 0 (buffer length = TotLength) 
pointer definition record parameter field must contain the size in 
bytes of the application buffer in which the device driver is to insert 
the sessions pointer image. All other words in the parameter list are 
returned to the application by MouGetPtrShape. 

If the buffer size is insufficient, the TotLength field will contain the 
actual size in bytes of the returned pointer image. 

The pointer shape may be set by the application via MouSetPtrShape 
or may be the default image provided by the installed Pointer Device 
Driver. 

Refer to the OS/2 Technical Reference Volume I for more information 
concerning the Pointer Draw device driver. 
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Purpose 

MouGetScaleFact returns a pair of 1-word scaling factors for the 
current mouse device. 

Calling Sequence 

EXTRN MouGetScaleFact: FAR 

PUSH@ OTHER ScaleStruct ; 2-word structure 
PUSH WORD DeviceHandle ;Mouse device handle 
CALL MouGetScal eFact 

Where 

Sca/eStrucf 

is where the mouse device driver's current row and column coor- 
dinate scaling factors are returned to the caller by the mouse 
device driver. 

ScaleStruct is a control bloci< structure that is written into by the 
mouse support. The format of the ScaleStruct structure is: 

WordO 

=RowScale, the current row coordinate scaling factor. 
Rowscale falls within the following limits: 

1 <= return value <= (32k - 1) 

Word 1 

= ColScale, the current column coordinate scaling factor. 
ColScale falls within the following limits: 

1 <= return value <== (32k - 1) 

See "MouSetScaleFact - Set Mouse Scaling Factor" on 
page 4-42 for more information. 

DeWceHand/e 

contains the handle of the mouse device obtained from a previous 
MouOpen. 
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Get Mouse Scaling Factors 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

None 
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Purpose 

MoulnitReal initializes the DOS mode mouse device driver. 
Calling Sequence 

EXTRN MoulnitReal: FAR 

PUSH@ ASCIIZ DriverName ; Pointer draw driver name 
CALL MoulnitReal 

Where 

DriverName 

contains tlie name of tlie Mouse Pointer Draw Device Driver used 
as tlie pointer image drawing routine for the DOS mode session. 

The name of the device driver must be included in the 
CONFIG.SYS file at system boot time. Applications that use the 
default Pointer Draw Device Driver supplied by the system, must 
push a double word of Oes in place of an address. 

Currently the Shell uses the default image drawing routine sup- 
plied by the system and, consequently, places a double word of Os 
in place of an address. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

MoulnitReal is issued by the Shell (System Session Manager) at shell 
initialization time. 

The DOS mode mouse API (INT 33H), in contrast to the OS/2 mode 
Mouse API, does not contain an OPEN command. In addition, there 
may be only one session for DOS mode and, therefore, only one DOS 
mode mouse support. 
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The default pointer draw routine for the DOS mode is located in the 
screen pointer draw module used in the OS/2 mode. The OS/2 mode 
mouse support knows the address of this screen pointer draw routine. 
Establishing addressability to the screen pointer draw routine for the 
DOS mode mouse driver must be done at run time. The entry point of 
the screen pointer draw routine must be passed to the DOS mode 
mouse device driver. MoulnitReal passes the address of the default 
screen pointer draw routine to the DOS mode device driver at system 
initialization time so it is transparent to applications. 
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Purpose 

MouOpen opens the mouse device for the current session. 
Calling Sequence 

EXTRN MouOpen: FAR 

PUSH@ ASCIIZ Dn'verName ;Po1nter draw driver name 

PUSH@ WORD DeviceHandle ;Mouse device handle 

CALL MouOpen 

Where 

DrIverName 

contains the name of the Mouse Pointer Draw Device Driver used 
as the pointer image drawing routine for the session. 

The name of the device driver must be included in the 
CONFIG.SYS file at system start-up time. Applications that use 
the default Pointer Draw Device Driver supplied by the system 
must push a double word of Oes in place of an address. 

Applications that use the default image drawing routine supplied 
by the system must push a double word of Os in place of an 
address. 

DeWceHand/e 

is where the mouse support returns a 1 word value that repres- 
ents the mouse handle to the application. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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Remarks 

MouOpen generates a new mouse device handle every time it is 
called. 

MouOpen initializes tlie Mouse functions to a l<nown state. The appli- 
cation may have to issue additional mouse functions to establish the 
environment it desires. For example, after the MouOpen, the colli- 
sion area is defined to be the size of the entire display. Therefore, to 
get the pointer to be displayed, the application must issue a 
MouDrawPtr to remove the collision area. 

The initial state of the mouse is: 

• Row/Col scale factors set to 16/8. (See "MouSetScaleFact - 
Set Mouse Scaling Factor" on page 4-42.) 

• all events reported. (See "MouSetEventMasIc - Set Mouse 
Event Mask" on page 4-34.) 

• empty event queue. (See "MouReadEventQue - Read Mouse 
Event Queue" on page 4-23 and "MouGetNumQueEl — Get 
Event Queue Status" on page 4-12.) 

• all user settable Device Status bits reset. (Set to 0. See 
"MouSetDevStatus - Set Mouse Device Status" on page 4-32.) 

• pointer set to center of screen. (See "MouSetPtrPos — Set 
Mouse Pointer Position" on page 4-36.) 

• pointer shape set to the default for the pointer device driver cur- 
rently registered in the session. (See "MouSetPtrShape — Set 
Mouse Pointer Shape" on page 4-38.) 

• collision area equal to full screen. (See "MouDrawPtr - Mouse 
Draw Pointer" on page 4-4 and "MouRemovePtr — Remove 
Mouse Pointer" on page 4-30.) 
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Purpose 

MouReadEventQue reads an event from the mouse device FIFO event 
queue, and places it in a structure provided by tlie application. 



Calling Sequence 

EXTRN MouReadEventQue : FAR 

PUSH@ OTHER Buffer 

PUSH© WORD ReadType 

PUSH WORD DeviceHandle 

CALL MouReadEventQue 



;10 byte Structure address 
;Read type 

;Mouse device handle 



Where 

Buffer 

is a 10 byte structure in application storage wiiere tiie FIFO event 
record element from the mouse event queue for the currently 
installed mouse device driver will be returned to the application. 
The return data has the following format: 

MouState WORD (see below) 

EventTime DWORD (time since boot in milliseconds) 

Row WORD (absolute/relative row position) 

Col WORD (absolute/relative col position) 

MouState 

represents the state of the mouse at the time the event is 
reported. This word is defined as follows: 



Bit # Meaning 

7-15 - Reserved = 0 

6 - set if, button 3 down 

5 - set if, mouse motion, button 3 down 

4 - set if, button 2 down 

3 - set if, mouse motion, button 2 down 

2 - set if, button 1 down 

1 - set if, mouse motion, button 1 down 

0 - set if, mouse motion, no buttons down 
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ReadType 

indicates the action to take when MouReadEventQue is issued and 
the mouse event queue is empty. If the mouse event queue is not 
empty, this parameter is not examined by the mouse support. The 
ReadType values follow: 

0 - No WAIT for data on empty queue 

(return a NULL record) 

1 - WAIT lor data on empty queue 

DeWceHand/e 

contains the handle of the mouse device obtained from a previous 
MouOpen. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

The types of queued events are directly affected by the current value 
of the Mouse EventMask. MouSetEventMask is used to indicate the 
types of events desired, and MouGetEventMask is used to query the 
current value of the mask. Refer to these functions for further expla- 
nation of the masking of events. 

Recognition of the mouse transition depends on the use of MouState 
returned in the event record. The application should focus on bit 
transitions which occur in this word. It is important to properly set 
the event mask with MouSetEventMask for reporting the state transi- 
tions. 

MouState reports the state of the mouse which resulted from the 
action which caused the event. The action can be pressing or 
releasing a button, and/or moving the mouse. All status is given, 
regardless of the EventMask which was used to determine whether or 
not to report the event. 
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For example, assume the EventMask indicates tliat tlie application 
wishes only button 1 event. The EventMask will have only bits 1 and 
2 set in this case. Also assume the current state of the mouse is no 
buttons down, and mouse is not moving. At this point, button 1 is 
pressed causing an event; the status will show button 1 down (bit 2 
set). Next the mouse is moved, thereby causing more events; status 
will show bits 1 set. Finally, mouse is stopped and button 1 is 
released. The event will show status with no bits set. 

Next, button 2 is pressed. No event occurs. Mouse is then moved; 
again, no event. Then, while mouse is still in motion, button 1 is 
pressed; an event is generated with bits 1 and 3 set in the state word. 
While mouse is still in motion, both buttons are released. Because 
button 1 changes states, an event occurs. The state word will have 
bit 0 set. Finally, mouse is stopped. No event occurs, again because 
no button 1 transition has taken place. 
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Purpose 

MouRegister registers a mouse subsystem within a session. 
Calling Sequence 

EXTRN MouRegister: FAR 

PUSH@ ASCIIZ ModuleName ;Modu1e Name 

PUSH© ASCIIZ EntryName ; Entry Name 

PUSH DWORD Mask ; Function Mask 

CALL MouRegister 

Where 

ModuleName 

contains the dynamic linl< module name. The maximum length is 
129 bytes (including ASCIIZ terminator). 

EntryName 

contains the dynamic Wnk entry point name of a routine that 
receives control when any of the registered functions are called. 
The maximum length is 33 bytes (including ASCIIZ terminator) 

Mask 

is a masl< of bits, where each bit set to 1 identifies a Mouse func- 
tion being registered. The bit mask format is shown below: 



Bit# 


Function Registered 


31-21 


-Reserved = 0 


20 


-MouSetDevStatus 


19 


-MoulnitReal 


18 


-MouSetPtrPos 


17 


-MouGetPtrPos 


16 


-MouRemovePtr 


15 


-MouDrawPtr 


14 


-MouSetPtrShape 


13 


-MouGetPtrShape 


12 


-MouClose 


11 


-MouOpen 


10 


-Reserved 
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09 
08 
07 
06 
05 
04 
03 
02 
01 
00 



-MouSetEventMask 

-MouSetScaleFact 

-MouGetEventMask 

-MouGetScaleFact 

-MouReadEventQue 

-MouGetNumQueEl 

-MouGetDevStatus 

-MouGetNumMickeys 

MouGetNumButtons 



-Reserved 



Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

The Base Mouse Subsystem is the default mouse subsystem. There 
can be only one MouRegister outstanding at a time without an inter- 
vening MouDeRegister. MouDeRegister must be issued by the same 
process that issued MouRegister. 

When any registered function is called, control is routed to 
EntryName. When this routine is entered, four additional values are 
pushed onto the stack. The first is the index number (WORD) of the 
function being called. The second is a near pointer (WORD). The 
third Is the caller's DS register (WORD). The fourth is the return 
address (DWORD) to the mouse router. For example, if 
MouGetNumMickeys were called and control routed to EntryName, 
the stack would appear as if the following instructions were executed: 

PUSH@ WORD NumberOfMickeys 

PUSH WORD DevlceHandle 

CALL FAR MouGetNumMickeys 

PUSH WORD Function Code 

CALL NEAR entry point in Mouse Router 

PUSH DS 

CALL FAR EntryName 
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When a registered function returns to tlie Mouse Router, AX is inter- 
preted as follows: 

AX = 0 

No error. Do not invoke the Base Mouse Subsystem routine. 
Return AX = 0. 

AX = -1 

Invoke the Base Mouse Subsystem routine. Return AX = return 
code from the Base Mouse Subsystem. 

AX = error (not 0 or -1) 

Do not invoke the Base Mouse Subsystem routine. Return AX = 
error. 



When the mouse API router receives a mouse call, it routes it to the 
Base Mouse Subsystem unless an application or other mouse sub- 
system has previously issued MouRegister for that call. If the call 
was registered, the subsystem Is entered at the EntryName specified, 
and provided with the applicable function code. 

The registered function mask is used to determine whether a 
requested function will be performed by the registered mouse sub- 
system or default to the Base Mouse Subsystem. 

The following table shows the relationship of the mouse API calls and 
the function code passed to either the Base Mouse Subsystem or a 
registered mouse subsystem. 

MOU API Call Function Code 

MouGetNumButtons 00 

MouGetNumMickeys 01 

MouGetDevStatus 02 

MouGetNumQueEl 03 

MouReadEventQue 04 

MouGetScaleFact 05 

MouGetEventMask 06 

MouSetScaleFact 07 

MouSetEventMask 08 

Reserved 09 

Reserved OA 

MouOpen OB 
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MouClose 


OC 


MouGetPtrShape 


OD 


MouSetPtrShape 


OE 


MouDrawPtr 


OF 


MouRemovePtr 


10 


MouGetPtrPos 


11 


MouSetPtrPos 


12 


MoulnitReal 


13 


MouSetDevStatus 


14 



A registered mouse subsystem must leave the stack, on exit, in the 
exact state it was received. 
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Purpose 

MouRemovePtr allows a process to notify the mouse device driver 
that the area defined by the passed parameters is for the exclusive 
use of the application. This area is defined as the 'collision' area and 
is not available to the mouse device driver when drawing pointer 
images. 

Calling Sequence 

EXTRN MouRemovePtr: FAR 

PUSH@ OTHER PtrArea ; Address of pointer data b1ocl< 

PUSH WORD DeviceHandle :Mouse device handle 
CALL MouRemovePtr 

Where 

PtrArea 

is where the application provides a data structure to define the 
collision area. This structure is as follows: 

• UpLeftRow WORD Upper left row (pixels or chars) coordi- 
nates (word) 

• UpLeftCol WORD Upper left col (pixels or chars) coordinates 

(word) 

• LowRightRow WORD Lower Right row (pixels or chars) coor- 
dinates (word) 

• LowRightCol WORD Lower Right col (pixels or chars) coordi- 
nates (word) 

which the mouse device driver uses to define the collision area for 
the session pointer shape. 

Neither the upper left corner (UpLeftRow , UpLeftCol) nor the 
lower right corner (LoRightRow, LoRlghCol) of the collision area 
coordinate pair may overrun the display. An error will result if 
either of these coordinate pairs logically extends beyond the 
screen boundaries. 

Row and col values may be specified In either pixels or character 
units as long as the orientation Is preserved across all values in 
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the structure and the dimensional choice corresponds to the 
current display mode. 

DevlceHandle 

contains the handle of the mouse device obtained from a previous 
MouOpen. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

The application passes data to the mouse device driver to inform the 
mouse driver that the collision area described by the data is to be 
exclusively under the control of the application. This collision area is 
not to be modified by the mouse device driver. This causes the 
mouse device driver to remove the mouse pointer image from the 
screen if it is currently located within the collision area. The mouse 
device driver will not draw the pointer Image any time the image's 
logical location lies within the collision area. 

MouRemovePtr may be issued by any process in the session. 
However, only one collision area is active at a time. Each 
MouRemovePtr command has the effect of resetting the collision area 
to the location and area specified by the current command. Previ- 
ously defined collision areas are replaced and no longer checked for. 

if the logical pointer position is outside of the collision area specified 
by the latest MouRemovePtr command, the pointer image will be 
drawn. 

The MouDrawPtr command effectively cancels the MouRemovePtr 
command and allows the pointer to be drawn anywhere on the 
screen, until a new MouRemovePtr command is issued. 
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Purpose 

MouSetDevStatus sets the mouse device driver status flags for tlie 
mouse device driver currently installed. The status flags are a 2 byte 
set of bit flags. 

Calling Sequence 

EXTRN MouSetDevStatus: FAR 

PUSH© WORD DeviceStatus ; Status flags 

PUSH WORD DeviceHandle ;Mouse device handle 

CALL MouSetDevStatus 

Where 

DeviceStatus 

is v\^here the application places the desired status flag settings. 

The passed parameter is a 2 byte set of flags. Only the high order 
byte has any meaning. 

High byte 

Bit # Meaning 

07-02 -Reserved = 0 

01 -set if, mouse device is to return data in miclceys 
00 -set if, the interrupt level pointer draw routine is not to be 
called at interrupt time 

Low byte: 

Bit # Meaning 

07-00 -Reserved = 0 

DeviceHandle 

contains the handle of the mouse device obtained from a previous 
MouOpen. 
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Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

MouSetDevStatus is the complement to MouGetDevStatus. However, 
not all status flags may be set with MouSetDevStatus. Only the flags 
corresponding to the following functions may be modified: 

• return data in mickeys 

Normally, mouse data is returned to the application with the 
absolute display mode coordinates of the pointer image position 
on the display screen. By setting this status flag, mouse data will 
be returned in relative mickeys, a wait of mouse movement. 

• don't call pointer draw device 

Normally, the interrupt level screen pointer draw routine is called 
at interrupt time. The pointer draw routine projects the pointer 
image on the screen and then returns to the mouse device driver. 
By setting this status flag, the mouse device driver will not call 
the pointer draw routine. The application must draw any required 
pointer image on the screen. 
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Purpose 

MouSetEventMask assigns a new event mask to the current mouse 
device driver. 

Calling Sequence 

EXTRN MouSetEventMask: FAR 

PUSH© WORD EventMask ;Mouse device event mask ptr 

PUSH WORD DevlceHandle ;Mouse device handle 

CALL MouSetEventMask 

Where 

EventMask 

indicates what mouse events are to be placed on the event queue. 
The EventMask bit values are described below: 



Bit # Meaning 

07-15 - Reserved = 0 

06 - set to receive button 3 press/release events 

05 - set to receive button 3 press/release events, with 

mouse motion 
04 - set to receive button 2 press/release events 
03 - set to receive button 2 press/release events, with 

mouse motion 
02 - set to receive button 1 press/release events 
01 - set to receive button 1 press/release events, with 

mouse motion 
00 - set to mouse motion events with no button 

press/release events 



DeWceHand/e 

contains the handle of the mouse device obtained from a previous 
MouOpen. 
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Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

Setting a bit in the event masic means that the associated event wili 
be reported on the mouse FIFO event queue. See 
"MouReadEventOue - Read Mouse Event Queue" on page 4-23 for 
examples of event mask use. 
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Set Mouse Pointer Position 



Purpose 

MouSetPtrPos directs the mouse driver to set a new current row and 
column coordinate position for the mouse pointer shape. 

Calling Sequence 

EXTRN MouSetPtrPos: FAR 

PUSH@ OTHER PtrPos ; Double word structure 

PUSH WORD DeviceHandle :Mouse device liandle 

CALL MouSetPtrPos 

Where 

PtrPos 

structure format follows: 

Word 0 = 

pointer row coordinate screen position. 
Word 1 = 

pointer column coordinate screen position. 

Both parameters must be in pixel or character units, depending on 
the mode setting of the display in the session. 

Coordinate positions are relative to physical displacement from 
the top left corner of the display screen. 

DeviceHandle 

contains the handle of the mouse device obtained from a previous 
MouOpen. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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Remarks 

The application must insure that the coordinate position specified 
conforms to the current display mode orientation for the session. 
Pixel values must be used for graphics modes and character values 
for text modes. 

This function has no effect on the display's current collision area defi- 
nition as specified by the MouDrawPtr call. If the mouse pointer 
image is directed into a defined collision area, the pointer image will 
not be drawn until either enough pointer movement has been gener- 
ated to locate the pointer image beyond the collision area or the colli- 
sion area is released by the MouDrawPtr call. 
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Purpose 

MouSetPtrShape allows a process to set the pointer shape and size 
to be used as the mouse device driver pointer image for all applica- 
tions in a session. 



Calling Sequence 

EXTRN MouSetPtrShape : FAR 

PUSH? OTHER PtrBuffer 

PUSH@ OTHER PtrDefRec 

PUSH WORD DevlceHandle 

CALL MouSetPtrShape 



; Pointer shape buffer 

; Pointer definition record 

;Mouse device handle 



Wliere 

PtrBuffer 

Is where the application stores the bit image the mouse device 
driver uses as the pointer shape for that session. The buffer con- 
sists of AND and XOR pointer masks in a format meaningful to the 
Pointer Draw Device Driver. 

For CGA compatible text modes (0, 1, 2, and 3) the following 
describes the AND and XOR pointer mask bit definitions for each 
character cell of the masks. 

Bits Meaning 

15 - Blinking 

14-12 - Background Color 

11 - Intensity 

10-8 - Foreground Color 

7-0 - Character 

PtrDefRec 

is a structure in application storage where the application stores 
the necessary data for the pointer device driver to build an Row 
by Column image for each bit plane for the currently running 
display mode. 

The pointer definition record structure is described below: 
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Word 0 = TotLength 

Word 1 = Col 

Word 2 = Row 

Word 3 =ColOffset 

Word 4 = RowOffset 

TotLength 

contains the total length in bytes of the data necessary for the 
Mouse Pointer Draw Device Driver to build a Row by Column 
image for each bit plane for the currently running display mode. 

The following example illustrates how to compute the TotLength 
for the system supplied Mouse Pointer Draw Device Driver: 

Mono and Text - 

TotLength = (height in characters) * 

(width in characters) * 2 * 2 
=1*1*2*2 
= 4 

Note: as stated above, for text mode height and width must be 1, 
so length is always 4. 

Graphics - 

TotLength = (height in pixels)* 

(width in pixels)*(bits per pixel) * 2 / 8. 

Note: width-in-pixels must be a multiple of 8. 

Modes 4 and 5 (32G x 200) 

TotLength = (height) * (width) * 2 * 2 / 8. 
Mode 6 (64Q x 200) 

TotLength = (height) * (width) * 1 * 2 / 8. 

Co/ 

for graphics modes: is a full-word that contains the pixel width 
(columns) of the mouse shape for the session. This width must be 
greater than or = to 1. 

for text modes, column must = 1. 
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Row 

for graphics modes: is a full-word that contains the pixel height 
(row) of the mouse shape for the session. Row must be greater 
than or = to 1. 

For Text modes, Row must = 1. 
ColOffset 

is the relative column pixel offset for the pointer image which is 
used for coordinate tracking. This defines the column coordinate 
for the pointer image hotspot. This value is a signed number that 
represents character or pixel offset, depending on the display 
mode. 

RowOffset 

is the relative row pixel offset for the pointer Image which is used 
for coordinate tracking. This defines the row coordinate for the 
pointer image hotspot. This value is a signed number that repres- 
ents pixel offset, depending on the display. Length calculations 
produce byte boundary buffer sizes. 

For other custom displays and for the extended modes of the EGA 
attachment, it Is possible to initialize the display to modes that 
require multiple bit planes. In these cases, the area sized by the 
Row and Col limits must be repeated for each bit plane supported 
in that mode. Consequently, the calling process must supply 
enough data to allow the mouse device driver to draw the pointer 
shape on all currently supported bit planes in that session. 

Note: For text modes, row and column offset must equal 0. 

DeWceHancf/e 

contains the handle of the mouse device obtained from a previous 
MouOpen. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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Remarks 

An application passes a data image to the mouse device driver, 
which the mouse driver applies to the screen whenever the logical 
pointer position is not located in the application-defined collision 
area. The application synchronizes use of the screen with the mouse 
driver by way of MouRemovePtr and MouDrawPtr. 

The pointer shape is dependent on the display device driver used to 
support the display device. OS/2 supports text and graphics modes. 
These modes are restricted to modes 0 through 7, depending on the 
display device. Character modes (modes 0, 1, 2, 3, and 7) support the 
pointer cursor only as a reverse block character. This reverse block 
character has a character height and width = 1. 

The pointer shape is mapped by the Pointer Draw Device Driver and 
determined completely by the application. The height and width may 
vary from 1 through the pixel size of the display screen. For 
restrictions concerning the Pointer Draw Device Driver, see OS/2 
Technical Reference, Volume 1. 

Note: The current pointer shape in effect for the session may be 
determined with "MouGetPtrShape - Get Pointer Shape" on 
page 4-14. 
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Purpose 

MouSetScaleFact assigns to the current mouse device driver a new 
pair of 1-word scaling factors. 

Calling Sequence 

EXTRN MouSetScal eFact : FAR 

PUSH© OTHER ScaleStruct ; 2-word structure 
PUSH WORD DeviceHandle :Mouse device handle 
CALL MouSetScaleFact 

Where 

ScaleStruct 

is where the mouse device driver's new row and column coordi- 
nate scaling factors are obtained by the mouse device driver. 

ScaleStruct is a data structure supplied by the application. The 
format of the ScaleStruct structure follows: 

Word 0 = RowScale 

the new row coordinate scaling factor. RowScale must conform 
to the following limits: 

1 <= value <= (32k-1) 

Word 1 = CoiScale 

the new column coordinate scaling factor. CoiScale must 
conform to the following limits: 

1 <= value <= (32k-1) 

DeWceNand/e 

contains the handle of the mouse device obtained from a previous 
MouOpen. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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Remarks 

MouSetScaleFact sets the mickey to pixel ratio for mouse motion. 
The row scale and column scale ratios specify a number of mickeys 
per 8 pixels. The default value for the row scale is 8 mickeys per 8 
pixels. The default value for the column scale is 16 mickeys to 8 
pixels. 

The number of pixels moved, does not have to correspond 1 to 1 with 
the number of mickeys the mouse moves. The scaling factor defines 
a sensitivity for the mouse, which is a ratio of the number of mickeys 
required to move the cursor 8 pixels on the screen. The sensitivity 
determines at what rate the cursor moves on the screen. 
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Purpose 

MouSynch provides synchronous (serial) access for a mouse sub- 
system to the mouse device driver. 

Calling Sequence 

EXTRN MouSynclirFAR 

PUSH WORD lOWait ; Indicate wait/no wait 

CALL MouSyncli 

Where 

lOWait 

indicates whether to wait for access. 
The fiagword bits are defined as follows: 



Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

MouSynch requests an exclusive system semaphore (See 
"DosCloseSem - Close System Semaphore" on page 2-19). This 
semaphore request clears when the subsystem returns to the Mouse 
Router. MouSynch blocks all other threads within a session until the 
semaphore clears (returns from the subsystem to the router). To 
ensure proper synchronization, MouSynch should be issued by a 
mouse subsystem if it intends to access dynamically modifiable 



15-1 - 
0 - 



if bit 0 = 0 



If bit 0 = 1 



Description 

reserved equal to 0 

indicates whether caller wants to wait if mouse 
device is busy 

requestor waits until mouse device driver is 
free 

control immediately returned to caller 
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per-session shared data or if it intends to issue a DosDevlOCtl. 
MouSyncli will not protect globally shared data from threads in other 
sessions. 
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Chapter 5. OS/2 Video Function Caiis 



This chapter reflects the video API interface only. Each function call 
reflects the most frequently occurring error codes only. For an exten- 
sive listing of all error codes, refer to the Appendix at the back of this 
book. 

For information regarding other functional characteristics of the video 
API, refer to the IBM Operating System/2 Technical Reference, 
Volume 1 
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Purpose 

VioDeRegister deregisters a video subsystem previously registered 
witiiln a session. VioDeRegister must be issued by tlie same process 
tliat issued the previous VioRegister. After VioDeRegister Is issued, 
subsequent video calls are processed by the Base Video Subsystem. 

Calling Sequence 

EXTRN VioDeRegister: FAR 
CALL VioDeRegister 

Where 

none 

Returns 

IF AX = 0 then NO error code 
ELSE AX = error code 

Remarks 

none 



5-2 



VIoEndPopUp - 
Deallocate Pop-Up Display Screen 



Purpose 

VioEndPopUp is issued by tlie appiication wlien it no longer requires 
tlie temporary screen obtained tlirougli a previous VioPopUp call. 

Calling Sequence 

EXTRN VioEndPopUp: FAR 

PUSH WORD VioHandle ;V1o device handle 

CALL VioEndPopUp 

Where 

VioHandle 

is a reserved word of Os. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

When the appiication issues a VioEndPopUp call, all video calls are 
directed to the application's normal video buffer. 
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Purpose 

VioGetAnsi returns tlie current ANSI status On/Off state 
Calling Sequence 

EXTRN VioGetAnsi: FAR 

PUSH© WORD Indicator ;0n/0ff indicator (returned) 

PUSH WORD VioHandle ;Vio handle 

CALL VioGetAnsi 

Where 

Indicator 

Is where the current ANSI status is returned. A value of 1 indicates 
ANSI is active, and a value of 0 indicates ANSI is not active. 

VioHandle 

is a reserved word of Os. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

None 
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Purpose 

VioGetBuf returns the address of the logical video buffer {LVB). 
Calling Sequence 

EXTRN VioGetBuf: FAR 

PUSH© DWORD LVBPtr ; Points to LVB 

PUSH@ WORD Length ; Length of buffer 

PUSH WORD VioHandle :Vio handle 

CALL VioGetBuf 

Where 
LVBPtr 

contains the selector and offset of the logical video buffer. Appli- 
cations should not assume the offset portion of this far address 
will be 0. 

Length 

is the length of the returned buffer in bytes. The length is 
Number of rows * Number of columns * 2 

VioHandle 

is a reserved word of Os. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

With VioGetBuf, an application can prepare a screen in the applica- 
tion's own logical video buffer (LVB) offline. When the application is 
in the foreground, the physical screen buffer is updated from the LVB 
when VioShowBuf is issued. When the application runs in the back- 
ground, the physical screen buffer is updated when the application is 
switched to the foreground. 
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Once VioGetBuf is issued, all VioWrtXX calls issued while the applica- 
tion Is running in the foreground are written to the physical display 
buffer and LVB. 

VioGetBuf is not supported in graphics modes. 

Use VioGetMode to determine the dimensions of the buffer. 
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Purpose 

VioGetConfig returns the video display configuration. 
Calling Sequence 

EXTRN VioGetConfig: FAR 

PUSH WORD Reserved ; Reserved (must be 0) 

PUSH@ OTHER ConfigData ; Configuration data 

PUSH WORD VioHandle ;Vio handle 

CALL VioGetConfig 

Where 

Reserved 

is a word of Os. 

ConfigData 

is a structure where the display configuration is returned. 

Size Description 

WORD Length 

WORD Adapter type 

WORD Display type 

DWORD Memory 

Length 

is an input parameter to VioGetConfig. It specifies the 
length of the data structure in bytes including itself. For 
OS/2 the maximum size structure required is 10 bytes. 
Adapter Type 

is the display adapter type. 

• 0 = reserved 

• 1 = color graphics adapter 

• 2 = enhanced graphics adapter 

• 3 = VGA or IBM Personal System/2™ Display Adapter 

• 4-6 = reserved 

• 7 = IBM Personal System/2™ Display Adapter 8514/A 
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Display Type 

is tlie dispiay/monitor type. 

• 00 = reserved 

• 01 = color display 

• 02 = enlianced color display 

• 03 = IBM Personal System/2 Monochrome Display 8503 

• 04 = IBM Personal System/2 Color Displays 8512 and 
8513 

• 05-08 = reserved 

• 09 = IBM Personal System/2 Color Display 8514 
Memory 

is the amount of memory on the adapter in bytes. It is 
returned as a 32-bit value. 

VioHandle 

is a reserved WORD of Os. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

The values returned for Adapter Type and Display Type specify the 
configuration the Base Video Subsystem assumes is present. The 
Base Video Subsystem determines this information by making 
various tests, for example, testing the switch settings on the card. 
This interface does not guarantee that the display corresponding to 
the display type returned is actually present. There may be no 
monitor attached to the adapter. Also, if the switch settings on the 
card are set inappropriately, the Base Video Subsystem (BVS) may 
assume that one display type is present when another is in its place. 
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Purpose 

VioGetCp allows a process to query the code page currently used to 
display text data. 

Calling Sequence 

EXTRN VioGetCp: FAR 

PUSH WORD Reserved ; 

PUSH@ WORD CodePagelD :Code page ID 

PUSH WORD VioHandle ; Video handle 

CALL VioGetCp 

Where 

Reserved 

is a reserved word of Os. 

CodePagelD 

is a word in the application's data area. The current video code 
page is returned in this word. 

VioHandle 

is a reserved word of Os. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

The display code page ID previously set by VioSetCp or inherited 
from the requesting process is returned to the caller. 

The code page tag returned will be the currently active code page. A 
value of 0000 indicates that the code page in use is the ROM code 
page provided by the hardware. 
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Purpose 

VioGetCurPos returns the cursor position. 
Calling Sequence 

EXTRN VioGetCurPos: FAR 

PUSH© WORD Row ;Row return data 

PUSH@ WORD Column ; Column return data 

PUSH WORD VioHandle :Vio handle 

CALL VioGetCurPos 

Where 
Row 

is tlie current row position of the cursor where 0 is the top row. 
Column 

is the current column position of the cursor where 0 is the leftmost 
column. 

VioHandle 

is a reserved word of Os. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

None 
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Purpose 

VioGetCurType returns the cursor type. 
Calling Sequence 

EXTRN VioGetCurType: FAR 

PUSH@ OTHER CursorData ; Cursor characteristics 

PUSH WORD VioHandle ;Vio handle 

CALL VioGetCurType 

Where 

CursorData 

is wliere characteristics of the cursor are returned. 

Size Description 

WORD Cursor start line 

WORD Cursor end line 

WORD Cursor width 

WORD Cursor attribute 

CursorStartLine 

is the horizontal scan line in the character cell which marl<s the 
top line of the cursor. If the character cell has "n" scan lines, 0 is 
the top scan line of the character cell and"n"-1 is the bottom scan 
line. 

CursorEndLine 

is the horizontal scan line in the character cell which marl^s the 
bottom line of the cursor. Scan lines within a character cell are 
numbered as defined under CursorStartLine. 

Cursor Width 

Is the width of the cursor in columns. The maximum value sup- 
ported by the OS/2 Base Video Subsystem is 1 . CursorWidth = 0, 
specifies the default width (one column) 

CursorAttrib 

is the attribute of the cursor. 

• - 1 = hidden 
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• Any other value is normal. 

VioHandle 

Is a reserved word of Os. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Family API Considerations 

Sonne options operate differently in the DOS nnode than they do in the 
OS/2 mode. Therefore, the following restriction applies to 
VioGetCurType when coding in the DOS mode : 

VioGetCurType returns only two values for CursorAttrib; 0 = visible 
cursor, and -1 = hidden cursor. 

Remarks 

None 
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Purpose 

VioGetFont returns either tlie font table of tlie size specified, or the 
font currently in use. 

Calling Sequence 

EXTRN VioGetFont: FAR 

PUSH@ OTHER RequestBlock ; Request block 

PUSH WORD VioHandle :V1o handle 

CALL VioGetFont 

Where 

RequestBlock 

is a data structure that contains the request. The content of the 
structure varies depending upon the request type. The request 
type is in the second word. The formats of the supported request 
bloclcs are shown below. The symbols in the rightmost column 
are defined as follows: 

• I = input parameter 

• O = output parameter 





Get Current Font (EGA, VGA, or 

IBM Personal System/2 Display Adapter 




WORD 


Length of structure (in bytes including length 
itself) = 14 


1 


WORD 


Request type = 0, get current font 


1 


WORD 


Pel columns in character ceil 


0 


WORD 


Pel rows in character cell 


0 


DWORD 


A caller-supplied data area where the requested 
font table is returned. If the specified address is 
0, a system-supplied segment that contains the 
requested font table is returned. 


I/O 
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Get Current Font (EGA, VGA, or 

IBM Personal System/2 Display Adapter 




WORD 


Length in bytes of the caller-supplied data area 
where the font table is returned. 


I/O 





Get ROM Font (CGA, EGA, VGA, or 

or IBM Personal System/2 Display Adapter) 




WUnU 


Length of structure (In bytes including length 
itself) = 14. 


1 
1 


WORD 


Request type = 1, get ROM font. 


1 


WORD 


Pel columns in character cell 


1 


WORD 


Pel rows In character cell 


1 


DWORD 


a caller- supplied data area where the 
requested font table is returned. If the speci- 
fied address is 0, a system-supplied 
segment that contains the requested font 
table is returned. 


I/O 


WORD 


Length in bytes of the caller-supplied data 
area where the font table is returned. 


I/O 



VloHandle 

Is a reserved word of Os. 



Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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Remarks 

For request type = one, return ROM font, the font size requested must 
be supported by the display adapter installed. The 8x8, 8x14, 9x14, 
8x16, or 9x16 character font may be requested for the VGA or IBM 
Personal System/2 Display Adapters adapters. The 8x8, 8x14, or 9x14 
font may be requested for the enhanced graphics adapter. The 8x8 
font may be requested for the color graphics adapter. 

For request type = one, return ROM font, the far address returned 
will be a ROM pointer only for those fonts where the font table for the 
full 256-character set is actually contained in ROM. Otherwise, the 
far address returned will be a RAM pointer. Note that for 8x8 the font 
table for the full 256-character set is returned. For 9x14 or 9x16 the 
font table for the full 256-character set is also returned. Partial fonts 
are not returned. The 9x14 and 9x16 fonts are derived from variations 
of the 8x14 and 8x16 fonts, respectively, where the fonts for those 
characters which are different are replaced. 

For VioGetFont specifying request type = one, return ROM font, the 
font returned is derived from the fonts contained in the system, EGA, 
VGA, and IBM Personal System/2 Display Adapter BIOS data areas 
as applicable. One exception is: for the EGA, VGA and IBM Personal 
System/2 Display Adapter, if VioSetCp has been issued, the font of 
the size requested from the active code page is returned. 
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Purpose 

VioGetMode returns the mode of the display. 
Calling Sequence 

EXTRN VioGetMode: FAR 

PUSH@ OTHER ModeData ;Mode characteristics 

PUSH WORD VioHandle :Vio handle 

CALL VioGetMode 

Where 
ModeData 

is the structure where mode characteristics are returned. 



Size 


Description 


WORD 


Length 


BYTE 


Type 


BYTE 


Color 


WORD 


Text Columns 


WORD 


Text Rows 


WORD 


Horizontal Resolution 


WORD 


Vertical Resolution 



Length 

is an Input parameter to VioGetMode. Length specifies the length 
of the data structure in bytes including length itself. The value 
specified on input controls the amount of mode data returned. 
The minimum structure size required is 3 bytes, and the maximum 
structure size required is 12 bytes. Any value specified for Length 
other than 3 must be an even number. 

Type 

is a bit masl< of mode characteristics. The definitions of the bits 
follows: 
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xxxxxxxb b = 0 monochrome compatible mode 

b = 1 other 
xxxxxxbx b = 0 text mode 

b = 1 graphics mode 
xxxxxbxx b = 0 enable color burst 

b = 1 disable color burst 

Color 

is the number of colors defined as a power of 2. This is equivalent 
to the number of color bits that define the color. For example: 

• Color = 1 specifies 2 colors 

• Color = 2 specifies 4 colors 

• Color = 4 specifies 16 colors 

Text Columns 

are the number of text columns. 

Text Rows 

are the number of text rows. 

Horizontal Resolution 

is the number of pel columns. 

Vertical Resolution 

is the number of pel rows. 

VioHandle 

is a reserved word of Os. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

Refer to "VIoSetMode - Set Display Mode" on page 5-67 for exam- 
ples. 
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Purpose 

VioGetPhysBuf gets addressability to tlie physical display buffer. 
Calling Sequence 

EXTRN VioGetPhysBuf: FAR 

PUSH@ OTHER Structure ;Data structure 
PUSH WORD Reserved ; Reserved (must be 0) 
CALL VioGetPhysBuf 

Where 

structure 

is a data structure that contains the physical display buffer 
address and length on input and the selectors, used to address 
the display buffer, on output. The data structure is defined as 
follows: 

Size Description 

DWORD Buffer start address 
DWORD Buffer length 
OTHER Selector list 

Buffer Start Address 

is the physical display buffer specified as a 32-bit physical 
address. 

Buffer Length 

Is the 32-bit length of the physical display buffer. 

Selector List 

is where the selectors (each of word-length) used to address the 
physical display buffer are returned. The first selector returned in 
the list addresses the first 64K of the physical display buffer or 
Buffer Length, whichever is smaller. If Buffer Length is greater 
than 64K bytes, the second selector addresses the second 64K 
bytes, and so on. The last selector returned In the list addresses 
the remainder of the display buffer. The application is responsible 
for ensuring enough space is reserved for Selector List to accom- 
modate the specified Buffer Length. 
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Reserved 

is a word of Os. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

An application uses VioGetPhysBuf to get addressability to the phys- 
ical display buffer. The selector returned by VioGetPhysBuf may be 
used only when an application program is executing in the fore- 
ground. When an application wants to access the physical display 
buffer, the application must call VioScrLock. VioScrLock either waits 
until the program is running in the foreground or returns a warning 
when the program is running in the background. For more informa- 
tion refer to "VioScrLock - Lock Screen" on page 5-48 and 
"VioScrllnLock - Unlock Screen" on page 5-58 

The buffer range specified for the physical screen buffer must fall 
between AOOOO and BFFFF inclusive. An application may issue 
VioGetPhysBuf only when it |s running in the foreground. An applica- 
tion may issue VioGetPhysBuf more than once. 
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Purpose 

VioGetState returns the current settings of the palette registers, over- 
scan (border) color or blink/background intensity switch. 

Calling Sequence 

EXTRN VioGetState: FAR 

PUSH@ OTHER RequestBlocIc ; Request block 
PUSH WORD VioHandle ;V1o liandle 
CALL VioGetState 

Where 

RequestBlock 

is a data structure that contains the request. The content of the 
structure varies depending on the request type. The request type 
is in the second word. The formats of the request blocks sup- 
ported are shown below. The synnbols in the right column have 
the following meanings: 

• I = input parameter 

• O = output parameter 





Get Palette Registers (EGA, VGA, or 
IBM Personal System/2 Display Adapter ) 




WORD 


Length of structure (in bytes including length 
itself) maximum length = 38. 


1 


WORD 


Request type = 0, Get palette registers 


1 


WORD 


First palette register to return. Must be in range 
0 to 15. The palette registers are returned in 
sequential order. The number of palette regis- 
ters returned is based upon the length of the 
structure. 


1 



5-20 



VioGetState - 
Get Video State 





Get Palette Registers (EGA, VGA, or 
IBM Personal System/2 Display Adapter ) 




1 or 
more 


1 WORD that contains the color value for each 
palette register returned. 


0 






Get Overscan (Border) Color (CGA, VGA, or 
IBM Personal System/2 Display Adapter) 




WORD 


Length of structure (In bytes Including length 
Itself) = 6 


1 


WORD 


Request type = 1, get overscan (border) color 


1 


WORD 


Color value 


O 






Get Blink/Background Intensity Switcli 
(CGA, EGA, VGA, or 

IBM Personal System/2 Display Adapter) 




WORD 


Length of structure (in bytes including length 

itself) = 6 


1 


WORD 


Request type = 2, get blink/ background intensity 
switch 


1 


WORD 


Value = 0, blinking foreground colors enabled. 
Value = 1, high intensity background colors 
enabled. 


0 



VioHandle 

Is a reserved word of Os. 



Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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Remarks 

None 
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Purpose 

VioModeUndo allows one thread within a process to cancel a 
VioModeWait issued by another thread within the same process. 

Calling Sequence 

EXTRN VioModeUndo: FAR 

PUSH WORD Ownerlndic ; Ownership indicator 

PUSH WORD Kill Indie ; Terminate indicator 

PUSH WORD Reserved ; Reserved (must be 0) 

CALL VioModeUndo 

Where 
Ownerlndic 

indicates whether the thread Issuing VioModeUndo wants owner- 
ship of VioModeWait to be reserved for its process. 

• If Ownerlndic = 0, reserve ownership 

• If Ownerlndic = 1, give up ownership. 

Kinindic 

indicates whether the thread (with the outstanding VioModeWait) 
should be returned an error code or be terminated. 

• If Killlndic = 0, return error code 

• If Killlndic = 1, terminate thread. 

Reserved 

is a reserved word of Os. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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Remarks 

VioModellndo may be issued only by a thread within the process 
which owns VioModeWait. The thread issuing VioModellndo can 
either reserve ownership of the VioModeWait function for its process 
or give up ownership. The thread whose VioModeWait is cancelled is 
optionally terminated. 



5-24 



VioModeWait - 
Restore Mode Wait 



Purpose 

VioModeWait allows a graphics mode application to be notified when 
it must restore its video mode, state, and modified display adapter 
registers. The return from this function call provides the notification. 

Calling Sequence 

EXTRN VioModeWait: FAR 

PUSH WORD RequestType ; Request type 

PUSH@ WORD Notify Type ;Notify type (returned) 

PUSH WORD Reserved ; Reserved (must be 0) 

CALL VioModeWait 

Where 

RequestType 

indicates the event the application is waiting for. RequestType = 
0 indicates the application wants to be notified at the end of a 
pop-up to restore its mode. RequestType = 0 is the only event 
supported by VioModeWait. 

NotifyType 

specifies the operation to be performed by the application upon 
return from VioModeWait. NotifyType = 0, indicating restore 
mode, is the only type of notification returned. 

Reserved 

Is a reserved word of Os. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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Remarks 

A VioModeWait thread is notified to perform a restore at the com- 
pletion of an application or hard error pop-up. Refer to 
"VioPopUp - Allocate a pop-up Display Screen" on page 5-28 for 
further discussion. The VioModeWait thread of the session that was 
originally interrupted for the pop-up is notified. The VioModeWait 
thread must restore the video mode, state, and modified display 
adapter registers and Immediately re-Issue VioModeWait. The 
VioModeWait thread does not restore the physical display buffer. 
OS/2 saves/restores the physical display buffer over a pop-up. 

Only one process for a session can issue VioModeWait. The first 
process that issues VioModeWait becomes the owner of this function. 
(Refer to "VioModeUndo - Restore Mode Undo" on page 5-23.) 

An application must issue VioModeWait only If it writes directly to the 
registers on the display adapter. Otherwise, If VioModeWait is not 
issued, OS/2 restores the physical display buffer, mode, and state at 
the completion of a pop-up. 

A graphics mode application (or a text mode application which writes 
directly to the registers on the display adapter) must Issue 
VIoSavRedrawWait. (Refer to "VioSavRedrawWalt - Screen Save 
Redraw Wait" on page 5-45.) 

A VioModeWait thread should not issue any file system or loader DOS 
calls (or calls to any dynamic linl< routines which issue these file 
system or loader DOS calls). Otherwise, a system lockout will occur 
in the following scenario: 

1. One of the threads of a process running In the foreground causes 
a hard error. 

2. A hard error pop-up is displayed. At the completion of the 
pop-up, a VioModeWait thread (In the same process which 
caused the hard error) is notified to perform a restore. 

3. The VioModeWait thread issues a file system or loader DOS call. 
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An application that contains a VioModeWait thread should be 
designed to avoid any hard errors while the VioModeWait thread is 
running. If hard errors occur, there is a potential for a system lockout 
to occur. 
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Purpose 

VioPopUp is issued by an application process wlien it requires a tem- 
porary screen to display a momentary message to the user. 

Calling Sequence 

EXTRN VioPopUp: FAR 

PUSH@ WORD Options ; Opt ion Flags 

PUSH WORD VioHandle ;Vio handle 

CALL VioPopUp 

Where 

Options 

contain bit flags that indicate which of the various options avail- 
able to the application are being selected. The flags bits are 
described below: 

High byte = 0 

Low byte=: 

Bit Meaning 

7-2 - Reserved = 0 

1 - O=non-transparent operation. The video mode is set to 
text - mode 3, 3*, 3+ , 7 or 7 + . The highest resolution 
supported by the primary display adapter configured in 
the system is selected. The screen is cleared, and the 
cursor is positioned in the upper left corner of the display. 

1 =transparent operation. If the video mode of the out- 
going foreground session is text (mode 2, 3, 7 or 1 of the * 
or + variations of these modes), no mode change occurs. 
The screen is not cleared, and the cursor remains in its 
current position. If transparent operation is selected, and 
if the video mode of the outgoing foreground session is 
not text (or if the outgoing foreground session has a 
VioSavRedrawWait thread), the pop-up request is refused. 
A unique error code is returned in this case. 
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OS/2 is responsible for saving and restoring the pliysical 
display buffer of the previous foreground session around a 
pop-up. This is true whether transparent or 
non-transparent operation is selected. 
0 - 0=return with unique error code if pop-up Is not imme- 
diately available and 1=walt If pop-up Is not Immediately 
available. 

VioHandle 

Is a reserved word of Os. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

VioPopUp is normally Issued by the application when it is running in 
the background and wishes to Immediately display a message to the 
user without waiting to become the active foreground session. 

When an application process Issues VioPopUp, it should wait for the 
return from the request. If the process allows any of its threads to 
write to the screen before VioPopUp returns a successful return code, 
the screen output may be directed to the application's normal video 
buffer rather than to the pop-up screen. If the process allows any of 
its threads to issue keyboard or mouse calls before VioPopUp returns 
a successful return code, the Input will be directed from the applica- 
tion's normal session. Once the process which issued VioPopUp 
receives a successful return code, video and keyboard calls issued 
by any of the threads In the pop-up process are directed to the pop-up 
screen. This will continue until the process issues VioEndPopUp 
phen.up. At that time video and keyboard calls resume being 
directed to the application's normal video buffer. 

There may be only one pop-up in existence at any one time. If a 
process requests a pop-up and a pop-up already exists, the process 
has the choice of waiting for the prior pop-up to complete or receiving 
an immediate return with an error code. The error code will indicate 
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that the operation failed due to an existing pop-up having captured 
the screen. 

Vio pop-ups provide a mechanism for a background application to 
notify the operator of an abnormal event upon which the operator 
must take some action. When considering the suitability of using 
pop-ups in a particular situation, the possible disruptive effect of 
pop-ups to the operator should be considered. If the operator were 
interrupted frequently by pop-ups issued by background applications, 
the operator would not be able to work effectively with the foreground 
application. 

While a video pop-up is in the foreground, the operator cannot use 
the hot key to switch to another application or the shell. Before the 
operator can switch another application or the shell to the fore- 
ground, the pop-up application must Issue VIoEndPopUp 

While a video pop-up is In effect, all video calls from the previous 
foreground session are blocked until the process that Issued 
VioPopUp issues VioEndPopUp 

When VioPopUp is issued, only the process within the session that 
issued VioPopUp is brought to the foreground. Assuming the session 
was already the foreground session, any video calls issued by other 
processes in that session are blocked until the process that issued 
VioPopUp issues VioEndPopUp 

DosExecPgm may not be issued by a process during a pop-up. The 
following video calls are the only calls that may be issued by a 
process that issued VioPopUp during the pop-up: 
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VioEndPopUp 

VioGetConfIg 

VioGetCp 

VioGetFont 

VioGetAnsi 

VioGetState 

VioGetCurPos 

VioGetCurType 

VioGetMode 

VioReadCharStr 

VioReadCellStr 

VioScrolIRt 

VioScrollUp 



VioScrollDn 

VioScrollLf 

VioSetCurPos 

VioSetCurType 

VioSetCp 

VIoSetFont 

VioSetState 

VIoWrtNChar 

VIoWrtNAttr 

VioWrtNCell 

VioWrtCharStr 

VioWrtCharStrAtt 

VioWrtCellStr 

VioWrtTTY 



Selectors to the physical display buffer, which the issuing process 
obtained on a prior VioGetPhysBuf call, may not be used during the 
pop-up. 

When an application registers a replacement for VioPopUp within a 
session, the registered routine is only invoked when that session is in 
the foreground. If VioPopUp is issued when that session is in the 
bacl<ground, the OS/2 default routine is invoked. If the application's 
session is using a keyboard or mouse monitor, the monitor will not 
intercept data while the pop-up is active. 
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Purpose 

VioPrtSc copies tlie screen to tlie printer. 
Calling Sequence 

EXTRN VioPrtSc: FAR 

PUSH WORD VIoHandle :V1o handle 
CALL VioPrtSc 

Where 

VIoHandle 

is a reserved word of Os. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

VioPrtSc supports text modes 0 througli 3, 7, and tlie + and * vari- 
ations of these modes. An Alternate Video Subsystem may want to 
register a replacement for VioPrtSc. The Base Video Subsystem 
does not support PrtSc in graphics modes. 

VioPrtSc is reserved for use by the session manager. Application 
programs may not Issue VioPrtSc. 
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Purpose 

VioPrtScToggle is calied by tlie Session Manager wlien tlie operator 
presses Ctrl-PrtSc. 

Calling Sequence 

EXTRN VioPrtScToggle: FAR 

PUSH WORD VioHandle :Vio handle 
CALL VioPrtScToggle 

Where 

VioHandle 

is a reserved word of Os. 

Returns 

IF AX = 0 tlien NO error 
ELSE AX = error code 

Remarks 

VioPrtScToggle toggles tlie Ctrl-PrtSc state of the foreground session. 
When the Ctrl-PrtSc state is on, all VioWrtTTY calls from that session 
are echoed to the print device. 

VioPrtScToggle can only be called by the session manager. If an 
application issues this call, it will receive an error code. 

Three beeps are generated if a hard error is detected while writing to 
the printer. When Ctrl-PrtSc is turned off, the operator may have to 
press the Enter key to cause output spooled while Ctrl-PrtSc was 
active to be printed. 
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Purpose 

VioReadCellStr reads a string of cliaracter-attribute pairs (or cells) 
from the screen starting at the specified location. 

Calling Sequence 



EXTRN 


VioReadCellStr: FAR 




PUSH@ 


OTHER 


CellStr 


;Cell string buffer 


PUSHia 


WORD 


Length 


; Length of cell string buffer 


PUSH 


WORD 


Row 


•.Starting row location 


PUSH 


WORD 


Col umn 


; Starting column location 


PUSH 


WORD 


VioHandle 


; Video handle 


CALL 


VioReadCellStr 





Where 

CellStr 

Is the buffer into which the cell string is read. 
Length 

is the length of the buffer in bytes. Length must take into account 
that each character-attribute entry in the buffer is 2-bytes. If the 
length of the buffer is not sufficient, the last entry will not be com- 
plete. 

Row 

is the starting row of the field to read where 0 is the top row. 
Column 

is the starting column of the field to read where 0 is the leftmost 

column. 

VioHandle 

is a reserved word of Os. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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Remarks 

If a string read comes to the end of the line and is not complete, the 
string read continues at the beginning of the next line. If the read 
comes to the end of the screen and is not complete, the read termi- 
nates and the length is set to the length of the buffer that was filled. 
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Purpose 

VioReadCharStr reads a character string from the display starting at 
the specified location. 

Calling Sequence 

EXTRN VioReadCharStr: FAR 

PUSH@ OTHER CharStr 

PUSH@ WORD Length 

PUSH WORD Row 

PUSH WORD Column 

PUSH WORD VioHandle 

CALL VioReadCharStr 

Where 

CharStr 

is the buffer where the character string is read into. 
Length 

is the length of the buffer in bytes. 
Row 

is the starting row of the field to read where 0 is the top row. 
Column 

is the starting column of the field to read where 0 is the leftmost 
column. 

VioHandle 

Is a reserved word of Os. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 



; Character buffer 

; Length of buffer 

; Starting row location 

'.Starting column location 

; Video handle 
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Remarks 

If a string read comes to the end of the line and is not complete, then 
the string read continues at the beginning of the next line. If the read 
comes to the end of the screen and is not complete, the read termi- 
nates and the length is set to the number of characters read. 
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Purpose 

VioRegister registers an Alternate Video Subsystem witliin a session. 
Calling Sequence 

EXTRN VioRegister: FAR 

PUSH@ ASCIIZ ModuleName 

PUSH© ASCIIZ EntryPoint 

PUSH DWORD FunctionMaskl 

PUSH DWORD FunctionMasl(2 

CALL VioRegister 

Where 

ModuleName 

contains the dynamic iinic module name. The maximum length is 
129 bytes including the terminating byte of 0. 

EntryPoint 

contains the dynamic link entry point name of a routine that 
receives control when any of the registered functions are called. 
The maximum length is 33 bytes including the terminating byte of 
0. 

FunctionMaskl 

is a bit masW where each bit identifies a video function. The bit 
definitions are shown below. The first word pushed onto the stack 
contains the high order 16 bits of the function mask, and the 
second word contains the low order 16 bits. 



: Module name 
; Entry point name 
; Function mask 1 
; Function mask 2 
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Bit 


Registered Function 


31 


VioPrtScToggle 


30 


VioEndPopUp 


29 


VioPopUp 


28 


VioSavRedrawUndo 


27 


Vi oSavRed rawWait 


26 


VioScrUnLock 


25 


VioScrLock 


24 


VioPrtSc 


23 


VioGetAnsi 


22 


VioSetAnsi 


21 


VioScrolIRt 


20 


VioScrollLf 


19 


VioScrollDn 


18 


VioScrollUp 


17 


VioWrtCeliStr 


16 


VIoWrtCharStrAtt 


15 


VIoWrtCharStr 


14 


VioWrtTTY 


13 


VioWrtNCell 


12 


VioWrtNAttr 


11 


VioWrtNChar 


10 


VioReadCellStr 


09 


VioReadCharStr 


08 


VioShowBuf 


07 


VioSetMode 


06 


VIoSetCurType 


05 


VioSetCurPos 


04 


VIoGetPhysBuf 


03 


VioGetBuf 


02 


VioGetMode 


01 


VioGetCurType 


00 


VioGetCurPos 



FunctionMask2 

is a bit mask wliere eacli bit identifies a video function. Tlie bit 
mask lias the format sliown below. The first word pushed onto the 
stack contains the high order 16 bits of the function mask, and the 
second word contains the low order 16 bits. Unused bits are 
reserved and must be 0. 
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08 
07 
06 
05 
04 
03 
02 
01 
00 



Bit 

31-09 



Registered Function 

Reserved = 0 

VioSetState 

VioGetState 

VioSetFont 

VioGetCp 

VioSetCp 

VioGetConfig 

VIoGetFont 

VioModeUndo 

VioModeWait 



Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

An Alternate Video Subsystem must register which video calls it 
handles. The default OS/2 video subsystem is the Base Video Sub- 
system. 

When any of the registered functions are called, control is routed to 
EntryPoint. When this routine is entered, four additional values (5 
words) are pushed onto the stack. 

The first value is the index number (WORD) of the routine being 
called. The second value is a near pointer (WORD). The third value 
is the caller's OS register (WORD). The fourth value is the return 
address (DWORD) to the VIO router. 

For example, if VioSetCurPos were a registered function, the stacl< 
would appear as if the following instruction sequence were executed 
if VioSetCurPos were called and control routed to EntryPoint: 
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PUSH 


WORD 


Row 


PUSH 


WORD 


Column 


PUSH 


WORD 


VioHandie 


CALL 


FAR 


VioSetCurPos 


PUSH 


WORD 


Index 


CALL 


NEAR 


Entry point in Vio router 


PUSH 


WORD 


Caller's DS 


CALL 


FAR 


Dynamic link entry point 



Tlie index numbers that correspond to the registered functions are 
listed below: 



0 VioGetPhysBuf 


21 


VioScrolIRt 


1 VioGetBuf 


22 


VioSetAnsi 


2 VioShowBuf 


23 


VioGetAnsi 


3 VIoGetCurPos 


24 


VIoPrtSc 


4 VioGetCurType 


25 


VioScrLock 


5 VioGetMode 


26 


VioScrUnLock 


6 VioSetCurPos 


27 


VioSavRedrawWait 


7 VIoSetCurType 


28 


VioSavRedrawUndo 


8 VioSetMode 


29 


VioPopUp 


9 VioReadCharStr 


30 


VioEndPopUp 


10 VioReadCeilStr 


31 


VioPrtScToggle 


11 VioWrtNChar 


32 


VioModeWait 


12 VIoWrtNAttr 


33 


VioModeUndo 


13 VioWrtNCeli 


34 


VioGetFont 


14 VioWrtCharStr 


35 


VioGetConfig 


15 VIoWrtCharStrAtt 


36 


VioSetCp 


16 VioWrtCellStr 


37 


VioGetCp 


17 VioWrtTTY 


38 


VioSetFont 


18 VioScrollUp 


39 


VIoGetState 


19 VioSci'ollDn 


40 


VioSetState 



20 VioScrollLf 

When a registered function returns to the video router, the contents of 
AX are interpreted as follows: 

AX = 0 

No error. Do not Invoke the corresponding Base Video Subsystem 
routine. Return to caller with AX = 0. 
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AX = -1 

No error. Invoke the corresponding Base Video Subsystem 
routine. Return to caller with AX = return code from Base Video 
Subsystem. 

AX = error (not 0 or -1) 

Do not invoke the corresponding Base Video Subsystem routine. 
Return to caller with AX = error. 

When an application registers a replacement for VioPopUp within a 
session, the registered routine is only invoked when that session Is in 
the foreground. If VioPopUp Is issued when that session is in the 
background, the OS/2 default routine is Invoked. 

An Alternate Video Subsystem should be designed so that the rou- 
tines registered do not cause any hard errors when they are invoked. 
Otherwise, a system lockout will occur. Code and data segments of 
registered routines, which might potentially be loaded from diskette, 
must be preloaded. 



5-42 



VioSavRedrawUndo - 
Screen Save Redraw Undo 



Purpose 

VioSavRedrawUndo allows one thread within a process to cancel a 
VIoSavRedrawWait issued by another thread within the same 
process. 

Calling Sequence 

EXTRN VI oSavRedrawUndo : FAR 

PUSH WORD Ownerlndic ; Ownership indicator 

PUSH WORD Kill Indie ; Terminate indicator 

PUSH WORD VioHandle ; Video handle 

CALL VioSavRedrawUndo 

Where 

Ownerlndic 

indicates whether the thread issuing VioSavRedrawUndo wants 
ownership of VioSavRedrawWait to be reserved for its process. 

• If Ownerlndic = 0, reserve ownership 

• If Ownerlndic = 1, give up ownership 

Killlndlc 

indicates whether the thread with the outstanding 
VioSavRedrawWait should be returned an error code or be ternni- 
nated. 

• If Killlndlc = 0, return error code 

• If Killlndlc = 1, terminate thread 

VioHandle 

is a reserved word of Os. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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Remarks 

The issuing tliread can reserve ownersliip of VioSavRedrawWait for 
Its process or give It up. If a thread's VioSavRedrawWait Is can- 
celled, it is optionally terminated. VioSavRedrawUndo may be Issued 
only by a thread within the same process that owns 
VioSavRedrawWait. 
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Purpose 

VioSavRedrawWait notifies a grapiiics mode application wlien it must 
save or redraw its screen image. The return from tiiis function call 
provides the notification. The thread that issues the call performs the 
save or redraw and then re-issues VioSavRedrawWait to wait until its 
screen image must be saved or redrawn again. 

Calling Sequence 

EXTRN VioSavRedrawWait: FAR 

PUSH WORD SavRedrawIndic ; Save/redraw indicator 

PUSH© WORD Notify Type ;Notify type (returned) 

PUSH WORD VioHandle : Video liandle 

CALL VioSavRedrawWait 

Where 

SavRedrawIndic 

indicates which events the application is waiting for: 

if SavRedrawIndic = 0 

the session manager notifies the application for both save and 
redraw operations. 

If SavRedrawIndic = 1 

the session manager notifies the application for redraw oper- 
ations only. 

NotifyType 

specifies the operation to be performed by the application upon 
return from VioSavRedrawWait: 

0 = save screen image 

1 = restore screen image 

VioHandle 

is a reserved word of Os. 
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Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

OS/2 uses VioSavRedrawWait to notify a graphics mode application 
to save or restore Its screen image at screen switch time. The appli- 
cation in the outgoing foreground session is notified to perform a 
save. The application In the incoming foreground session Is notified 
to perform a restore. The application must perform the action 
requested and immediately re-issue VioSavRedrawWait. When an 
application performs a save, it saves its physical display buffer, video 
mode, and any other information the apph'cation needs to completely 
redraw its screen at restore time. 

Only one process per session can issue VioSavRedrawWait. The 
process that issues VioSavRedrawWait first, becomes the owner of 
the function. 

A text mode application must issue VioSavRedrawWait only if the 
application writes directly to the registers on the display adapter. 
Assuming VioSavRedrawWait Is not issued by a text mode applica- 
tion, OS/2 performs the required saves and restores. 

An application that issues VioSavRedrawWait may also need to issue 
VIoModeWalt. This would allow the application to be notified when it 
must restore its mode at the completion of an application or hard 
error popup. Refer to "VioModeWait - Restore Mode Wait" on 
page 5-25 for more information. Two application threads would be 
required to perform these operations in this case. 

At the time a VioSavRedrawWait thread is notified, the session Is In 
transition to/from the bacl<ground. Although the session's official 
status is background, any selector to the physical display buffer pre- 
viously obtained by the VioSavRedrawWait process (through 
VioGetPhysBuf) is valid at this time. The physical display buffer 
must be accessed without issuing VioScrLock. Since the session's 
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official status is background, any thread which issues VioScrLock 
with the "wait if unsuccessful" option will in fact wait. 

An application containing a VioSavRedrawWait thread should be 
designed so that the process does not cause any hard errors while 
the VioSavRedrawWait thread is running. Otherwise, there is a 
potential for a system lockout situation to occur. 

An application's VioSavRedrawWait thread may be notified to 
perform a restore before it is notified to perform a save. This would 
happen if the application was running in the background the first time 
it issued VioSavRedrawWait. 

Note: that the OS/2 Start command starts an application in the back- 
ground. 
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Purpose 

VioScrLock requests ownership of (locics) tlie physical dispiay buffer. 
Calling Sequence 

EXTRN VioScrLock: FAR 

PUSH WORD WaitFlag ;Block or not 

PUSH@ BYTE Status ;Lock status (returned) 

PUSH WORD VioHandle ; Video handle 

CALL VioScrLock 

Where 

WaitFlag 

indicates whether the process should biocic until the screen I/O 
can take place. 

• 0 = return if screen I/O not available 

• 1 = wait until screen I/O Is available 

Status 

indicates whether the lock is successful. 

• 0 = lock successful 

• 1 = lock unsuccessful (in the case of no wait) 

• Status is returned only when AX = 0. 

• Status = 1 may be returned only when WaitFlag = 0. 

VioHandle 

is a reserved word of Os. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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Family API Considerations 

Some options operate differently in the DOS mode than they do in the 
OS/2 mode. Therefore, the following restriction applies to VjoScrLock 
when coding in the DOS mode : 

The status will always indicate the lock is successful (AX = 0) 
Remarks 

This function call permits a process to determine if I/O to the physical 
screen buffer can take place. This prevents the process from writing 
to the physical buffer when the process is in the background. Proc- 
esses must cooperate with the system in coordinating screen 
accesses. 

Screen switching is disabled while the screen lock is in place. If a 
screen switch is suspended by a screen lock, and if the application 
holding the lock does not issue VioScrUnLock within a system-defined 
time limit, the screen switch occurs, and the process holding the lock 
is frozen in the background. A process should yield the screen lock 
as soon as possible to avoid being frozen when running in the back- 
ground. The timeout on the lock does not begin until a screen switch 
is requested. 

When the screen lock is in effect and another thread in the same or 
different process (in the same session) issues VioScrLock, the second 
thread receives an error code. VioScrUnLock must be issued by a 
thread within the same process that issued VioScrLock. 
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VioScrollDn - 
Scroll Screen Down 



Purpose 

VioScrollDn scrolls the entire display buffer (or area specified within 
the display buffer) down 

Calling Sequence 

EXTRN VioScrollDn: FAR 

PUSH WORD TopRow 

PUSH WORD LeftCol 

PUSH WORD BotRow 

PUSH WORD RIghtCol 

PUSH WORD Lines 

PUSH@ OTHER Cel 1 

PUSH WORD VioHandle 

CALL VioScrollDn 

Where 
TopRow 

Is the top row of the area to scroll. 
LeftCol 

is the left column of the area to scroll. 
BotRow 

is the bottonn row of the area to scroll. 
RightCol 

is the right colunnn of the area to scroll. 
Lines 

is the number of lines to be inserted at the top of the screen area 
being scrolled. If 0 is specified, no lines are scrolled. 

Cell 

is a character-attribute pair (two bytes) used as a fill character on 
inserted lines. 

VioHandle 

is a reserved word of Os. 



;Top row 
;Left column 
; Bottom row 
; Right column 
•.Number of lines 
;Cell to be written 
; Video handle 
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Scroll Screen Down 



Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

TopRow = 0 and LeftCol = 0 identifies the top left corner of the 
screen. 

If a value greater than the maximum value is specified for TopRow, 
LeftCol, BotRow, RightCol, or Lines, the maximum value for that 
parameter is used. 

If TopRow and LeftCol = 0 and if BotRow, RightCol, and Lines = 
65535 (or -1 in Assembler language), the entire screen will be filled 
with the character defined by Cell. 
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VioScrollLf - 
Scroll Screen Left 



Purpose 

VioScrollLf scrolls the entire display buffer (or area specified within 
the display buffer) left. 



Calling Sequence 

EXTRN VioScrollLf: FAR 

PUSH WORD TopRow 

PUSH WORD LeftCol 

PUSH WORD BotRow 

PUSH WORD Righted 

PUSH WORD Lines 

PUSH@ OTHER Cell 

PUSH WORD VioHandle 

CALL VioScrollLf 



;Top row 
;Left column 
•.Bottom row 
; Right column 
;Number of lines 
;Cell to be written 
: Video Handle 



Where 
TopRow 

is the top row of the area to scroll. 
LeftCol 

is the left column of the area to scroll. 
BotRow 

is the bottom row of the area to scroll. 
RightCol 

is the right column of the area to scroll. 
Lines 

is the number of columns to be inserted at the right of the screen 
area being scrolled. If 0 is specified, no lines are scrolled. 

Cell 

is a character attribute pair (two bytes) used as a fill character on 
inserted columns. 

VioHandle 

is a reserved word of Os. 
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Scroll Screen Left 



Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

TopRow = 0 and LeftCol = 0 identifies the top left corner of the 
screen. 

If a value greater than the maximum value is specified for TopRow, 
LeftCol, BotRow, RIghtCol, or Lines, the maximum value for that 
parameter is used. 

If TopRow and LeftCol = 0 and If BotRow, RIghtCol, and Lines = 
65535 (or -1 in Assembler language), the entire screen will be filled 
with the character defined by Cell. 
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VioScrolIRt - 
Scroll Screen Right 



Purpose 

VioScrolIRt scrolls the entire display buffer (or area specified within 
the display buffer) right. 



Calling Sequence 

EXTRN VioScrolIRt: FAR 

PUSH WORD TopRow 

PUSH WORD LeftCol 

PUSH WORD BotRow 

PUSH WORD RIghtCol 

PUSH WORD Lines 

PUSH0 OTHER Cell 

PUSH WORD VioHandle 

CALL VioScrolIRt 



;Top row 
;Left column 
; Bottom row 
: Right column 
•.Number of lines 
;Cen to be written 
; Video handle 



Where 
TopRow 

is the top row of the area to scroll. 
LeftCol 

is the left column of the area to scroll. 
BotRow 

is the bottom row of the area to scroll. 
RIghtCol 

is the right column of the area to scroll. 
Lines 

is the number of columns to be inserted at the left of the screen 
area being scrolled, if 0 is specified, no lines are scrolled. 

Cell 

Is a character attribute pair (two bytes) used as a fill character on 
inserted columns. 

VioHandle 

is a reserved word of Os. 
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VioScrolIRt - 
Scroll Screen Right 



Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

TopRow = 0 and LeftCol = 0 identifies the top left corner of the 
screen. 

If a value greater than the maximum value is specified for TopRow, 
LeftCol, BotRow, RightCol, or Lines, the maximum value for that 
parameter Is used. 

If TopRow and LeftCol = 0 and if BotRow, RightCol, and Lines = 
65535 (or -1 in Assembler language), the entire screen will be filled 
with the character defined by Cell. 
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VioScrollUp - 
Scroll Screen Up 



Purpose 

VioScrollUp scrolls the entire display buffer (or area specified within 
the display buffer) up. 



Calling Sequence 

EXTRN VioScrollUp: FAR 



PUSH WORD 

PUSH WORD 

PUSH WORD 

PUSH WORD 

PUSH WORD 



TopRow 
LeftCol 
BotRow 
Ri ghtCol 
Li nes 



PUSH@ OTHER Cell 
PUSH WORD VioHandle 
CALL VioScrollUp 



;Top row 
;Left column 
; Bottom row 
; Right column 
; Number of lines 
;Fill character 
; Video handle 



Where 

TopRow 

is the top row of the area to scroll. 
LeftCol 

is the left column of the area to scroll. 
BotRow 

is the bottom row of the area to scroll. 
RIghtCol 

is the right column of the area to scroll. 
Lines 

is the number of lines to be inserted at the bottom of the screen 
area being scrolled, if 0 is specified, no lines are scrolled. 

Cell 

is a character attribute pair (two bytes) used as a fill character on 
inserted lines. 

VioHandle 

Is a reserved word of Os. 
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Scroll Screen Up 



Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

TopRow=0 and LeftCol=0 identifies the top left corner of the screen. 

If a value greater than the maximum value Is specified for TopRow, 
LeftCol, BotRow, RightCol, or Lines, the maximum value for that 
parameter is used. 

If TopRow and LeftCol =0 and if BotRow, RightCol, and Lines=65535 
(or -1 In Assembler language), the entire screen will be filled with the 
character defined by Cell. 
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VioScrUnLock - 
Unlock Screen 



Purpose 

VioScrUnLock releases ownership of (uniocics) tiie pliysical display 
buffer. 

Calling Sequence 

EXTRN VioScrUnLock: FAR 

PUSH WORD VioHandle :V1deo handle 
CALL VioScrUnLock 

Where 

VioHandle 

Is a reserved word of Os. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Family API Considerations 

Some options operate differently in the DOS mode than they do in the 
OS/2 mode. Therefore, the following restriction applies to 
VioScrUnLock when coding in the DOS mode : 

The status will always indicate the unlock is successful (AX = 0). 

Remarks 

None. 
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Set ANSI On or Off 



Purpose 

VioSetAnsi activates or deactivates ANSI support. 
Calling Sequence 

EXTRN VioSetAnsi: FAR 

PUSH WORD Indicator :0n/0ff indicator 

PUSH WORD VioHandle :Video handle 

CALL VioSetAnsi 

Where 

Indicator 

equals 1 to activate ANSI support or 0 to deactivate ANSI. 

VioHandle 

is a reserved word of Os. 

Returns 

IF AX = 0 tlien NO error 
ELSE AX = error code 

Remarks 

For ANSI support, "ON" is the default. 
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VioSetCp - 
Set Code Page 



Purpose 

VioSetCp allows a process to set the code page used to display text 
data on the screen. 



Calling Sequence 

EXTRN VioSetCp: FAR 

PUSH WORD Reserved 

PUSH WORD CodePagelD 

PUSH WORD VIoHandle 

CALL VioSetCp 



CodePage Id 
Video handle 



Where 

Reserved 

is a reserved word of Os. 

CodePagelD 

must be equivalent to one of the code page ID's specified on the 
CONFIG.SYS CODEPAGE = statement or must specify the default 
ROM code page (0000). 

If the code page ID does not match one of the ID's on the 
CODEPAGE = statement, an error will result. Refer to IBM Oper- 
ating System/2 User's Reference for a complete description of 
CODEPAGE. 

VioHandle 

is a reserved word of Os. 



Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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VioSetCp - 
Set Code Page 



Remarks 

The code page tag specified must be eitlier 0000 or liave been speci- 
fied on the CONFIG.SYS CODEPAGE = statement. A value of 0000 
indicates that the code page is to be set to the ROM code page pro- 
vided by the hardware. 
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VioSetCurPos - 
Set Cursor Position 



Purpose 

VioSetCurPos sets the cursor position. 

Calling Sequence 

EXTRN VioSetCurPos: FAR 

PUSH WORD Row 

PUSH WORD Column 

PUSH WORD VIoHandle 

CALL VioSetCurPos 

Where 
Row 

is the new cursor row position where 0 is the top row. 
Column 

is the new cursor column position where 0 is the left column. 

VioHandle 

is a reserved word of Os. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

None 



;Row data 
; Column data 
; Video handle 
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VioSetCurType - 
Set Cursor Type 



Purpose 

VioSetCurType sets the cursor type. 
Calling Sequence 

EXTRN VioSetCurType: FAR 

PUSH@ OTHER CursorData ; Cursor characteristics 

PUSH WORD VIoHandle ; Video handle 

CALL VioSetCurType 

Where 

CursorData 

is a structure that contains the characteristics of the cursor. 

Size Description 

WORD Cursor start line 

WORD Cursor end line 

WORD Cursor width 

WORD Cursor attribute 

CursorStartLine 

is the horizontal scan line in the character cell which marks the 
top line of cursor. Note that if the character cell has N scan lines, 
0 is the top scan line of the character ceil and N-1 is the bottom 
scan line. 

CursorEndLine 

Is the horizontal scan line in the character cell which marks the 
bottom line of the cursor. Scan lines within a character cell are 
numbered as defined under CursorStartLine. The maximum value 
which can be specified for CursorEndLine is 31. The appearance 
of the cursor when the number of pel rows defined in the cursor Is 
greater than the number of pel rows in a character cell is variable 
depending upon the display adapter included in the configuration. 

Cursor Width 

is the width of the cursor in columns. The maximum value sup- 
ported by the OS/2 Base Video Subsystem is 1. CursorWidth = 0 
specifies the default width (one column). 



5-63 



VioSetCurType - 
Set Cursor Type 

CursorAttrib 

is the attribute of the cursor. 

Value = -1, is hidden. Any other value is normal. 

VIoHandle 

Is a reserved word of Os. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

None 
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VioSetFont - 
Set Font 



Purpose 

VioSetFont downloads a display font. The font being set must be 
compatible witli the current mode. 

Calling Sequence 

EXTRN VioSetFont: FAR 

PUSH@ OTHER RequestBlock ; Request block 
PUSH WORD VIoHandle ; Video handle 
CALL VioSetFont 



Where 

Reque^Block 

is a data structure that contains a request. The request type is 
contained in the second word. The format of the request block is 
shown below. The symbol In the right column has the following 
meaning: 

I - input parameter 



5-65 



VioSetFont - 
Set Font 





Set Current Font (EGA, VGA, or 

IBM Personal System/2™ Display Adapter) 




WORD 


Length of structure (in bytes including lengtli 
itself) = 14 


1 


WORD 


Request type = 0, set current font 


1 


WORD 


Pel columns in character cell 


1 


WORD 


Pel rows in character cell 


1 


DWORD 


Far address of a data area that contains the 
font table to set. 


1 


WORD 


Length in bytes of the data area that con- 
tains the font table to set. 


1 



VioHandle 

is a reserved word of Os. 



Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

When VioSetFont is issued, the current code page is reset. If 
VIoGetCp is subsequently issued, a unique error code is returned in 
AX. VioSetFont is applicable only for the enhanced graphics adapter, 
VGA or IBM Personal System/2 Display Adapter. 

Note: Return code, ERROR_VIO_USER_FONT represents a warning. 
It indicates that although the font could not be loaded into the adapter 
using the current mode, the font was saved for use with a later 
VioSetMode. 
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Set Display Mode 



Purpose 

VioSetMode sets the mode of the display. 
Calling Sequence 

EXTRN VioSetMode: FAR 

PUSH@ OTHER ModeData ;Mode characteristics 

PUSH WORD VioHandle ; Video handle 

CALL VioSetMode 

Where 
ModeData 

is a structure that contains the characteristics of the mode being 



set. 




Size 


Description 


WORD 


Length 


BYTE 


Type 


BYTE 


Color 


WORD 


Text Columns 


WORD 


Text Rows 


WORD 


Horizontal Resolution 


WORD 


Vertical Resolution 



Length 

is an Input parameter to VioSetMode. Length specifies the length 
of the data structure in bytes including Length itself. The 
minimum structure size required is three bytes, and the maximum 
structure size required is 12 bytes. Any value specified for Length 
other than 3 must be an even number. If a structure of length less 
than the maximum is specified, OS/2 will use default values for 
the remaining fields. 

I Type 

is a bit mask that contain specifications for the mode being set. 
The definitions of the bits follow: 
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Set Display Mode 

xxxxxxxb b = 0 monochrome compatible mode 
b = 1 other 

xxxxxxbx b = 0 text mode 

b = 1 graphics mode 
xxxxxbxx b = 0 enable color burst 

b = 1 disable color burst 

Color 

defines the nunnber of colors as a power of 2. This is equivalent to 
the number of color bits which define the color. For example, 

Color = 1 specifies 2 colors 
Color = 2 specifies 4 colors 
Color = 4 specifies 16 colors 
Color = 8 specifies 256 colors 

Color = 0 should be specified for 

monochrome modes 7, 7+, and F. 

Text Columns 

are the number of text columns. 

Text Rows 

are the number of text rows, are supported for The color graphics 
adapter supports 25 rows. The enhanced graphics adapter sup- 
ports 25 and 43 rows. The VGA adapter and the IBM Personal 
System/2™ Display Adapter support 25 and 50 rows. 

Horizontal Resolution 

is the number of pel columns. 

Vertical Resolution 

is the number of pel rows. 

VIoHandle 

is a reserved word of Os. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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Set Display Mode 



Remarks 

VioSetMode initializes the cursor position and type. VioSetMode will 
clear the screen in the DOS mode and in DOS 3.3. For all other envi- 
ronments, to clear the screen, use one of the VIoScrollxx calls. 

The disable color burst bit in the Type field in the VioSetMode data 
structure Is functional only for the color graphics adapter. For ail 
other display adapters the setting of this bit is returned on any subse- 
quent VioGetMode call but is otherwise ignored. 
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Set Display Mode 



EXAMPLES 




MnHp 9 

rlUUC C 




Type 


= 000G0101 






Text Columns 


= 80 


Text Rows 


= 25 


Horizontal Resolution 


= 640 


Vertical Resolution 


= 200 


Mode 3 




Type 


= 00000001 


\tM \ Ul 


t 


Text Columns 


= 80 


Text Rows 


= 25 


Horizontal Resolution 


= 640 


Vertical Resolution 


= 200 


Mode 3* 




Type 


= 00000001 


UU 1 UI 




Text Columns 


= 80 


Text Rows 


= 25 


Horizontal Resolution 


= 640 


Vertical Resolution 


= 350 


Mode 3+ 








Color 


= 4 


Text Col umns 


= 80 


Text Rows 


= 25 


Hori7ontal Rp^nliitinn 


= 720 


Vertical Resolution 


= 400 


Mode 5 




Type 


= 00000111 


Col or 


= 2 


Text Columns 


= 40 


Text Rows 


= 25 


Horizontal Resolution 


= 320 


Vertical Resolution 


= 200 
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Mode 6 

Type = 00000011 

Color = 1 

Text Columns = 80 

Text Rows = 25 

Horizontal Resolution = 640 

Vertical Resolution = 200 

Mode 7 

Type = 00000000 

Color = 0 

Text Columns = 80 

Text Rows = 25 

Horizontal Resolution = 720 

Vertical Resolution = 350 

Mode 7+ 

Type = 00000000 

Color = 0 

Text Columns = 80 

Text Rows = 25 

Horizontal Resolution = 720 

Vertical Resolution = 400 

Mode E 

Type = 00000011 

Color = 4 

Text Columns = 80 

Text Rows = 25 

Horizontal Resolution = 640 

Vertical Resolution = 200 

Mode F 

Type = 00000010 

Color = 0 

Text Columns = 80 

Text Rows = 25 

Horizontal Resolution = 640 

Vertical Resolution = 350 



VioSetMode - 
Set Display Mode 
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Mode IG 






Type 


= 


OOOOOOll 


Color 




4 


Text Columns 


= 


80 


Text Rows 


— 


25 


Horizontal Resolution 




640 


Vertical Resolution 




350 


Mode 11 






Type 


= 


OOOOOOll 


Col or 




1 


Text Columns 


= 


80 


Text Rows 




30 


Horizontal Resolution 




640 


Vertical Resolution 




480 


Mode 12 






Type 


= 


OOOOOOll 


Color 




4 


Text Columns 


__ 


80 


Text Rows 


- 


30 


Horizontal Resolution 




640 


Vertical Resolution 


— 


480 


Mode 13 






Type 




OOOOOOll 


Color 




8 


Text Columns 




40 


Text Rows 




25 


Horizontal Resolution 




320 


Vertical Resolution 




200 
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Set Video State 



Purpose 

VioSetState performs one of the following functions; sets palette reg- 
isters, sets tlie overscan (border) color or sets the blink/background 
intensity switch. 

Calling Sequence 

EXTRN VioSetState: FAR 

PUSH@ OTHER RequestBlock ; Request blocic 

PUSH WORD VioHandle -.Video handle 
CALL VioSetState 

Where 

RequestBlock 

is a data structure that contains the request. The content of the 
structure varies depending on the request type. The request type 
is contained in the second word. The formats of the supported 
request blocks are shown below. The symbol in the right column 
has the following meaning: 

• I - input parameter 
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Set Video State 





Set Palette Registers (EGA, VGA, or 
IBM Personal System/2 Display Adapter) 




WORD 


Length of structure (in bytes including lengtli 

itQPlf^ iTiAyimiim lonnth — ^ft 

llOvlly lliaAIIIIUIII IwllUill wO- 


1 


WORD 


Request type = 0, set palette registers 


1 


WORD 


First palette register to set. Must be in range 0 to 
15. The palette registers are set in sequential 
order. The number of palette registers set is 
based upon the length of the structure. 


1 


1 or 

more 

WORDS 


One WORD that contains the color value for each 
palette register being set. 


1 





Set Overscan (Border) Color (CGA, VGA, or 
IBM Personal System/2 Display Adapter) 




WORD 


Length of structure (in bytes including length 
itself) = 6 


1 


WORD 


Request type = 1, set overscan (border) color 


1 


WORD 


Color value 


1 





Set Blink/Background Intensity Switch 
(CGA, EGA, VGA, 

or IBM Personal System/2 Display Adapter) 




WORD 


Length of structure (in bytes including length 
itself) = 6 


1 


WORD 


Request type = 2, set blink/ background intensity 
switch 


1 
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Set Video State 





Set Blink/Background Intensity Switch 
(CGA, EGA, VGA, 

or IBM Personal System/2 Display Adapter) 




WORD 


Value = 0, enables blinking foreground colors. 
Value = 1, enables high intensity background 
colors 


1 



VIoHandle 

is a reserved word of Os. 



Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

None 
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Display Logical Buffer 



Purpose 

VioShowBuf updates the physical display buffer with the logical video 
buffer (LVB). 

Calling Sequence 

EXTRN VioShowBuf: FAR 

PUSH WORD Offset 

PUSH WORD Length 

PUSH WORD V1oHand1e 

CALL VioShowBuf 

Where 

Offset 

is the starting offset within the logical video buffer where the 
screen update begins. 

Lengih 

is the length of the area to be updated to the screen. 

VioHandle 

is a reserved word of Os. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

VioShowBuf is ignored unless the session is running in the fore- 
ground and some process within the session has previously called 
VioGetBuf. 

VioShowBuf is not supported in graphics modes. 



; Offset into LVB 

; Length 

: Video handle 
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Write Char/Attr String 



Purpose 

VioWrtCellStr writes a string of character-attribute pairs (cells) to the 
display. 

Calling Sequence 

EXTRN VioWrtCellStr: FAR 

PUSH@ OTHER CellStr 

PUSH WORD Length 

PUSH WORD Row 

PUSH WORD Column 

PUSH WORD VIoHandle 

CALL VioWrtCellStr 

Where 

CellStr 

is a string of character-attribute cells to be written. 
Length 

is the length of the string to be written in bytes. Each 
character-attribute cell is two bytes. 

Row 

is the starting cursor row to be written into where 0 is the top row. 
Column 

is the starting cursor column to be written into where 0 is the left 
column. 

VIoHandle 

is a reserved word of Os. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 



; String to be written 

; Length of string 

; Starting row position for output 

: Starting column position for output 

: Video handle 
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Write Char/Attr String 

Remarks 

If a string write comes to the end of the line and is not complete, the 
string write continues at the beginning of the next line. If the write 
comes to the end of the screen, the write terminates. 
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Write Character String 



Purpose 

VioWrtCharStr writes a cliaracter string to the display. 



Calling Sequence 



EXTRN VioWrtCharStr: FAR 



PUSH@ OTHER 

PUSH WORD 

PUSH WORD 

PUSH WORD 



CharStr 

Length 

Row 



; String to be written 
•.Length of character string 
;Starting row position for output 
; Starting column position for output 



Co1 umn 



PUSH WORD VioHandle ; Video handle 
CALL VioWrtCharStr 

Where 

CharStr 

is the character string to be written. 
Length 

is the iength of the character string in bytes. 
Row 

Is the starting cursor row to be written into where 0 Is the top row. 
Column 

is the starting cursor column to be written into where 0 is the left 
column. 

VioHandle 

is a reserved word of Os. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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Write Character String 



Remarks 

If a string write comes to the end of tlie line and Is not complete, the 
string write continues at the beginning of the next line. If the write 
comes to the end of the screen, the write terminates. 

Note: The string Is written to the display without changing any attri- 
butes. 



5-80 



VIoWrtCharStrAtt - 
Write Char String with Attr 



Purpose 

VioWrtCharStrAtt writes a character string with repeated attribute to 
the display. 



Calling Sequence 

EXTRN VioWrtCiiarStrAttrFAR 



pusm 


OTHER 


CharStr 


;String to be written 


PUSH 


WORD 


Length 


; Length of string 


PUSH 


WORD 


Row 


;Starting row position for output 


PUSH 


WORD 


Col umn 


; Starting column position for output 


PUSH@ 


OTHER 


Attr 


: Attribute to be replicated 


PUSH 


WORD 


VIoHandle 


; Video handle 


CALL 


VioWrtCliarStrAtt 





Where 

CharStr 

is the character string to be written. 
Length 

is the length of the character string in bytes. 
Row 

is the starting cursor row to be written into where 0 is the top row. 
Column 

Is the starting cursor column to be written Into where 0 Is the left 
column. 

Attr 

Is the attribute to be used in the display buffer for each character 
of the string written. 

VioHandle 

is a reserved word of Os. 
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Write Char String with Attr 



Returns 

IF AX = 0 then NO error 
ELSE AX = error code 

Remarks 

If a string write comes to the end of the line and is not complete, the 
string write continues at the beginning of the next line. If the write 
comes to the end of the screen, the write terminates. 
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Write N Attributes 



Purpose 

VioWrtNAttr writes an attribute to tlie display a specified number of 
times. 



Calling Sequence 

EXTRN VioWrtNAttr: FAR 



PUSH@ OTHER Attr 

PUSH WORD Times 

PUSH WORD Row 

PUSH WORD Column 

PUSH WORD VioHandle 

CALL VioWrtNAttr 



; Attribute to be written 
: Repeat count 

; Starting row position for output 
; Starting column position for output 
: Video handle 



Where 

Attr 

is tlie attribute to be written. 
Times 

is tlie number of times to write the attribute. 
Row 

is the starting cursor row to be written into where 0 is the top row. 
Column 

is the starting cursor column to be written into where 0 is the left 
column. 

VioHandle 

is a reserved word of Os. 



Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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VioWrtNAttr - 
Write N Attributes 

Remarks 

If 9 repeated write comes to the end of the line and is not complete, 
the write continues at the beginning of the next line. If the write 
comes to the end of the screen, the write terminates. 
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VioWrtNCell - 
Write N CharAAttrs 



Purpose 

VioWrtNCell writes a cell (or character-attribute pair) to the display a 
specified number of times. 



Calling Sequence 

EXTRN VioWrtNCell: FAR 



PUSH@ OTHER Cell 

PUSH WORD Times 

PUSH WORD Row 

PUSH WORD Column 

PUSH WORD VioHandle 

CALL VioWrtNCell 



;Cell to be written 
; Repeat count 

; Starting row position for output 
;Starting column position for output 
: Video handle 



Where 

CellStr 

Is the character-attribute cell (two bytes) to be written. 
Times 

is the number of times to write the cell. 
Row 

is the starting cursor row to be written into where 0 is the top row. 
Column 

is the starting cursor column position to be written, where 0 is the 
left column. 

VioHandle 

is a reserved word of Os. 



Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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VioWrtNCell - 
Write N Char/Attrs 

Remarks 

If a repeated write comes to the end of the line and is not complete, 
the write continues at the beginning of the next line. If the write 
comes to the end of the screen, the write terminates. 



5-86 



VioWrtNChar - 
Write N Characters 



Purpose 

VioWrtNChar writes a character to the display a specified number of 
times. 



Calling Sequence 

EXTRN VioWrtNChar: FAR 



PUSH@ OTHER Char 

PUSH WORD Times 

PUSH WORD Row 

PUSH WORD Column 

PUSH WORD VIoHandle 

CALL VioWrtNChar 



; Character to be written 
: Repeat count 

; Starting row position for output 
; Starting column position for output 
; Video handle 



Where 

Char 

is the character to be written. 
Times 

is the number of times to write the character. 
Row 

is the starting cursor row to be written into where 0 is the top row. 
Column 

is the starting cursor coiumn to be written into where 0 is the ieft 
column. 

VIoHandle 

is a reserved word of Os. 



Returns 

IF AX = 0 then NO error 
ELSE AX = error code 
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VioWrtNChar - 
Write N Characters 

Remarks 

if a repeated write comes to tlie end of tlie line and is not complete, 
tlie write continues at tlie beginning of the next line. If the write 
comes to the end of the screen, the write terminates. 
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VioWrtTTY - 
Write TTY String 



Purpose 

VioWrtTTY writes a cliaracter string to tlie display starting at the 
current cursor position. At the completion of the write, the cursor is 
positioned at the first position beyond the end of the string. 



Calling Sequence 

EXTRN VioWrtTTY: FAR 

PUSH© OTHER CharStr 

PUSH WORD Length 

PUSH WORD VioHandle 

CALL VioWrtTTY 



; String to be written 
;Lengtli of string 
; Video handle 



Where 

CharStrIng 

is the string to be written. 

Length 

is the length of the character string in bytes. 

VioHandle 

is a reserved word of Os. 

Returns 

IF AX = 0 then NO error 
ELSE AX = error code 



Remarks 

If a string write connes to the end of the line and is not complete, the 
string write continues at the beginning of the next line. If the write 
comes to the end of the screen, the screen is scrolled, and the write 
continues until completed. 

The characters carriage return, line feed, backspace, tab and bell are 
treated as commands rather than printable characters. Backspace is 
a non-destructive backspace. Tabs are expanded to provide standard 
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VioWrtTTY - 
Write TTY String 



8-byte-wide fields. VioWrtTTY is the only video call affected by 
Ctrl-PrtSc and ANSI. 

Characters are written using the current attribute defined by ANSI or 
the default value of X'07'. 
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Chapter 6. Generic lOCtI Commands 



OS/2 device drivers are used by OS/2 to access tlie I/O hardware. 
The lOCtI functions provide a method for an application, or sub- 
system, to send device-specific control commands to a device driver. 
The lOCtI functions are issued through the DosDevlOCtI API function 
request. The lOCtl functions are subfunctions of the DosDevlOCtI API 
function request. Applications should use the DosDevlOCtI function 
request for OS/2 Applications and the INT 21 H lOCtI request for DOS 
applications. See "DosDevlOCtI - I/O Control for Devices" on 
page 2-34 for additional Information. 

The category and function fields are determined as follows. Each 
code is contained in a byte. 

Category Code 



Category 


Code 


0 


OS/2 Defined 


1 


User Defined 


.XXX xxxx 


Code 


Function 


Code 


Function 


Code 


0 


Return error If unsupported 


1 


Ignore if unsupported 


.0 


Intercepted by OS/2 


.1 


Passed to driver 


..0 


Sends data and commands to device 


..1 


Queries data and information from device 


...X xxxx 


Subfunction 



Note that the sends/queries data bit is intended only to regularize the 
function set. It plays no critical role; some functions may contain both 
command and query elements. The convention is that such com- 
mands are defined as sends data. 
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Generic lOCtI Example 



Following is the calling sequence for the DosDevlOCtI call: 



EXTRN 


DosDevIOCtl :Far 




PUSH© 


OTHER Data 


;Data Packet 


PUSH@ 


OTHER ParmList 


; Parameter Packet 


PUSH 


WORD Function 


; Function Code 


PUSH 


WORD Category 


; Category Code 


PUSH 


WORD DevHandle 


; User's Device Driver File Handle 


CALL 


DosDevIOCtl 





The DosDevIOCtl call sends the request to the device driver request 
packet. The device driver receives the request packet, and looks for 
the Command Code (Command 16 is the Generic lOCti command) to 
identify the request. 

Note that each device driver can define the structure of the Data 
Packet and the Parameter Packet but all device drivers use the same 
request header. Refer to "DosDevIOCtl - I/O Control for Devices" 
on page 2-34 for more Information. 

The list of categories and functions for the GENERIC lOCfi request are 
summarized below.: 



FUNCTION 


DESCRIPTION 




Serial Device Control 


14H 


Reserved 


34H 


Reserved 


41 H 


Set baud (bit) rate 


42H 


Set line characteristics (stop, parity, data bits) 


44H 


Transmit Byte Immediate 


45H 


Break off 


46H 


Set modem control signals 


47H 


Behave as if XOFF received (stop transmit) 


48H 


Behave as if XON received (start transmit) 


49H 


Reserved 


4BH 


Break on 
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CAT FUNCTION DESCRIPTION 

53H Set Device Control Block (DCB) parameters 

61 H Return current baud (bit) rate 

62H Return line characteristics 

64H Return COM status 

65H Return transmit data status 

66H Return modem control output signals 

67H Return current modem input signals 

68H Return number of chars in receive queue 

69H Return number of chars in transmit queue 

6DH Return COM error 

721-1 Return COM event information 

73H Return Device Control Block (DCB) parameters 

02 Reserved 

03 Pointer Draw Control 

72H Get pointer draw address (pointer draw DD) 

04 Keyboard Control 
50H Set code page 

51 H Set input mode (default ASCII) 

52H Set interim character flags 

53H Set shift state 

54H Set typamatic rate and delay 

55H Notify of change of foreground session 

56H Set session manager Hot Key 

57H Set KCB 

58H Set code page ID 

5BH Reserved 

5CH Set NLS & custom code page 

71 H Get input mode 

72H Get interim character flags 

73H Get shift state 

74H Read character data record(s) 

75H Peek character data record 

76H Get session manager Hot Key 

77H Get keyboard type 

78H Get code page ID 

79H Translate scan code to ASCII 

05 Printer Control 
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CAT FUNCTION DESCRIPTION 



42H Set frame control (GPL, LPI) 

44H Set infinite retry 

45H Reserved 

46H Initialize printer 

48H Activate Font 

62H Get frame control 

64H Get infinite retry 

66H Get printer status 

69H Query Active Font 

6AH Verify Font 

06 Liglit Pen Control 

07 Mouse Control 

50H Allow ptr drawing after screen switch 

51 H Update screen display mode 

52H Screen switcher call 

53H Set scaling factors 

54H Set event mask 

55H Reserved 

56H Set pointer shape 

57H Unmark collision area 

58H Mark collision area 

59H Set pointer screen position 

5AH Set OS/2 mode pointer draw address 

5BH Set DOS mode pointer draw address 

5CH Set device status flags 

60H Get number of buttons 

61 H Get number of mickeys/centimeter 

62H Get device status flags 

63H Read event queue 

64H Get event queue status 

65H Get event mask 

66H Get scaling factors 

67H Get pointer screen position 

68H Get pointer shape Image 

69H Reserved 

08 Logical Disk Control 
OOH Lock drive 
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CAT FUNCTION 

01 H 
02H 
03H 
20H 
21H 
22H 
43H 
44H 
45H 
5EH 
5FH 
63H 
64H 
65H 

09 

OOH 
01 H 
44H 
63H 
64H 
65H 

10 

40H 

11 

01 H 
02H 
60H 

12-127 



DESCRIPTION 

Unlock drive 
Redetermine media 
Set logical map 
Block removable 
Get logical map 
Reserved 

Set device parameters 
Write track 

Format and verify track 

Reserved 

Reserved 

Get device parameters 

Read track 

Verify track 

Physical Disk Control 

Lock physical drive 

Unlock physical drive 

Physical write track 

Get physical device parameters 

Physical read track 

Physical verify track 

Character Device Monitor Control 

Register 

General Device Control 
Flush input buffer 
Flush output buffer 
Query monitor support 
Reserved Category Codes 



ASYNC (RS232-C) Generic lOCtI 



Wherever null pointer appears, It is the application's responsibility to 
set up a null pointer for the appropriate packet pointer before calling 
the device driver. lOCtIs nnay be interpreted differently by future 
releases if the pointer is not a null pointer. If a NULL POINTER is 
called for and a null pointer is not received by the device driver, it Is 
considered an invalid parameter or data packet value in this section. 

The application cannot assume a given timing relationship between 
when the lOCtIs are executed and when data is received or trans- 
mitted by the ASYNC hardware. 

Data Carrier Detect (DCD) is the same signal as Receiver Line Signal 
Detect (RLSD). 

The device driver services each communications port 
(C0M1, COM2, ...) independently. lOCtIs issued to the device driver 
for a given port have absolutely no effect on any other communi- 
cations ports that the device driver is servicing. 



Followino i5s a siimman/ nf Cateoorv 1 descrlDtlcns' 



Function 


Description 


14H 


reserved 


34H 


reserved 


41 H 


Set baud (bit) rate 


42H 


Set line characteristics (stop, parity, data bits) 


44H 


Transmit Byte Immediate 


45H 


Break off 


46H 


Set modem control signals 


47H 


Behave as If XOFF received (stop transmit) 


48H 


Behave as if XON received (start transmit) 


49H 


reserved 


4BH 


Break on 


53H 


Set Device Control Block (DCB) parameters 


61H 


Return current baud (bit) rate 


62H 


Return line characteristics 


64H 


Return COM status 


65H 


Return transmit data status 


66H 


Return modem control output signals 


67H 


Return current modem input signals 
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68H Return number of chars in receive queue 

69H Return number of chars In transmit queue 

6DH Return COM error 

72H Return COM event information 

73H Return Device Control Blocic (DCB) parametei's 



Category 1 — 
Function 41 H 



Purpose 

Set Baud Rate 



Parameter Packet Format 



Field 


Length 


Bit Rate 


WORD 


Data Packet Format 




None. Packet pointer nnust be NULL. 




Where 




Bit Rate 





The Bit Rate field is a binary integer representing the actual bit 
rate that the device driver should use to set the bit rate of the port. 
The valid values are: 

110 

150 

300 

600 

1200 

2400 

4800 

9600 

19200 (AT hardware not rated for this speed) 

An OPEN request packet will not cause the device driver to change 
the bit rate from its previous value. The initial value is 1200 baud. 

Returns 

If the call is made with invalid Parameter/Data packet values, a 
general failure error is reported. 
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Category 1 - 
Function 41 H 

Remarks 

If a general failure error Is not returned, the device driver will 
perform the action described in Bit Rate. 



6-9 



Category 1 - 
Function 42H 



Purpose 

Set Line Characteristics (stop bits, parity, data bits) 



Parameter Packet Format 



Field 


Length 


Data Bits 


BYTE 


Parity 


BYTE 


Stop Bits 


BYTE 


Data Packet Format 


None. Pacicet pointer must be NULL. 


Where 




Data Bit 




Value 


Meaning 


00H-04H 


reserved 


05H 


5 data bits 


06H 


6 data bits 


07H 


7 data bits (initial value) 


08H 


8 data bits 


09H-FFH 


reserved 


Parity 




Value 


Meaning 


OOH 


No parity 


01 H 


Odd parity 


02H 


Even parity (initial value) 


03H 


Mark parity (parity bit always 1) 


04H 


Space parity (parity bit always 0) 


06H-FFH 


reserved 
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Category 1 - 
Function 42H 



stop Bits 

Value Meaning 

OOH 1 stop bit (initial value) 

01H 1.5 stop bits (valid with 5 bit word length only) 

02H 2 stop bits (not valid with 5 bit word length) 

03H-FFH reserved 



Returns 

If the call Is made with invalid Parameter/Data packet values, a 
general failure error Is reported and the line characteristics are not 
changed for any parameters that were valid. 

Remarks 

If a general failure error is not returned, the device driver will set the 
line characteristics as defined. 

An OPEN request packet will not cause the device driver to change 
the line characteristics from its previous values. 

If the word length is less than 8 bits then the appropriate high order 
bits for received data will be 0 when placed in the receive queue by 
the device driver and when operated on by the device driver (for 
example, XON/XOFF checking, null stripping). This only applies to 
data that is received after the command is operated on by the device 
driver. Data already in the device driver receive queue is not 
affected In any way by a change in the word length. 

If the word length is less than 8 bits the device driver will not auto- 
matically truncate control/transmit data that the application may tell 
the device driver to operate on or use. No error will be reported by 
the device driver if transmit or control data given to the device driver 
has high order bits of non-0 value. 

I For example, if the device driver is told that the word length is 7 bits 
(high order bit of all data in receive queue from now on is 0) and the 
XOFF character is 80H then the device driver will never be able to 
recognize the XOFF character if automatic transmit flow control is 
enabled. If the error substitution character is set to 80H by the appli- 



6-11 



Category 1 - 
Function 42H 

cation with a word length of 7 currently being active, the device driver 
will still place an 80H in the receive queue. It is the responsibility of 
the application to maintain consistency between the requested word 
length for the COM device and the requests that the application 
makes of the device driver. 
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Category 1 - 
Function 44H 



Purpose 

Transmit Byte Immediate 



Parameter Packet Format 


Field 


Length 


Cliaracter to be Transmitted 


BYTE 


Data Packet Format 




Paclcet pointer must be NULL. 





Returns 

If the call is made with an invalid Data Packet value or if there is 
already another character waiting to be transmitted immediately due 
to a previous Category 1 Function 44H request that has not been ful- 
filled then a general failure error is reported and this request is 
ignored. A transmit immediate request is considered fulfilled when 
the character is given to the transmit hardware. 

Remarks 

If a general failure is not returned, the device driver will immediately 
transmit the byte contained in the Parameter Packet subject to the fol- 
lowing conditions: 

1 . If there is data currently in the transmit queue being transmitted, 
or waiting to be transmitted, the character to be transmitted 
Immediately will be placed at the logical front of the device driver 
transmit queue (not considered in transmit queue) so it is the next 
character to be given to the transmit hardware. If automatic 
receive flow control is enabled then a XON or XOFF character 
may or may not be placed ahead of the character to be trans- 
mitted immediately. 

2. This request always completes immediately (before the character 
is actually transmitted) even if the character may not be imme- 
diately transmitted for reasons discussed below. If there already 
is one character waiting to transmit immediately due to a pre- 



6-13 



Category 1 - 
Function 44H 



vious request then a general failure error will be returned and the 
application must mal<e this request again after there is no char- 
acter waiting to transmit immediately in the device driver 
transmit queue. Category 1 Function 64H (Return COM status) 
can be used to determine whether a character is currently waiting 
to be transmitted immediately. 

3. The device driver will not immediately transmit the character 
waiting to transmit immediately if the device driver is not trans- 
mitting characters due to modem control signal output hand- 
shaking (see Set Device Control Block (DCB) Category 1 Function 
53H Note 3) or if the device driver is currently transmitting a 
break. 

4. If the device driver is not transmitting characters due to auto- 
matic transmit or receive flow control (XON/XOFF) being enabled 
(with the proper set of conditions having happened, see Category 
1 Function 53H - Set Device Control Block (DCB)), or due to being 
asked to behave as if an XOFF character had been received (Cat- 
egory 1 Function 47H) then the device driver will still transmit a 
character that is waiting to be transmitted immediately due to this 
request. WARNING: An application which requests the device 
driver to transmit a character immediately when automatic 
transmit or receive flow control is enabled may cause unexpected 
results to happen to the communications line flow control pro- 
tocol. 

5. This is generally used to manually send XON and XOFF charac- 
ters. 

6. The character waiting to be transmitted immediately is not con- 
sidered part of the device driver transmit queue and is not 
flushed due to a flush request. XON/XOFF characters that are 
automatically transmitted due to automatic receive flow control 
may or may not be placed ahead of the character waiting to be 
transmitted immediately. Applications should not have depend- 
encies on this ordering. 
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Category 1 - 
Function 45H 



Purpose 

Set Break Off 




Parameter Packet Format 

None. Packet pointer must be NULL. 




Data Packet Format 




Field 


Length 


COM Error Word (COMERR) 


WORD 



Where 

COM Error Word 

The device driver returns this information if a general failure error 
is not reported. See Category 1 Function 6DH, Return COM Error, 
for COMERR definition. The COM device error Information Is not 
cleared by this action. 

Returns 

If the call Is made with an Invalid Parameter Packet value then a 
general failure error Is reported, this function is not performed, and 
valid information is not returned in the Data Packet. 

Remarks 

If a general failure error is not returned then the device driver will 
stop generating a break signal. It Is not considered an error if the 
device driver is not generating a break signal. The device driver will 
then resume transmitting characters taking into account all the other 
reasons why it may or may not transmit characters. 
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Category 1 - 
Function 46H 



Purpose 

Set Modem Control Signals 



Parameter Packet Format 



Field 


Length 


Modem Control Signals ON Mask 


BYTE 


Modem Control Signals OFF Mask 


BYTE 


Data Packet Format 


Field 


Lengtli 


COM Error Word (COMERR) 


WORD 



Where 

Modem Control Signals Value 

The device driver will set the modem control -signals as defined in 
this field. Bit 0 is DTR and bit 1 is RTS. If any other bits are 
set/reset by the masks then a general failure error results. The 
OFF mask contains a mask of the bits to turn off. The OFF mask 
has bits of 0 for the bits to turn off. The ON mask contains a mask 
of the bits to turn on. The ON mask has bits of 1 for the bits to turn 
on. If the Parameter Packet shows to turn off and on the same bit, 
the bit will be turned on. 

For example: 
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Category 1 - 
Function 46H 



Mask ON 



Mask OFF 



Meaning 

Set DTR 
Clear DTR 
Set RTS 
Clear RTS 



01 H 
OOH 
02H 
OOH 
03H 
OOH 



FFH 
FEH 
FFH 
FDH 
FDH 
FCH 



Set DTR and RTS 
Clear DTR and RTS 



If the DTR control mode input handshaking or the RTS control 
mode input handshaking or toggling on transmit is set then this 
request is not allowed to try to change the state of the modem 
control signal(s) that is (are) being used for input handshaking or 
toggling on transmit. If the request tries to modify a modem 
control signal that is being used for input handshaking or toggling 
on transmit then a general failure will result. 

COM Error Word 

The device driver returns this information if a general failure error 
is not returned to the application. See Category 1, Function 6DH, 
Return COM Error, for COMERR definition. The COM device error 
information is not cleared by this action. 

At device driver initialization, the device driver will turn OFF DTR 
and RTS for the COM devices that it owns. 

An OPEN request packet, when the COM device is not already 
open (from a previous open without a close) (first level open) will 
cause DTR and RTS to be set according to the DTR Control Mode 
and the RTS Control Mode. See Note 1 of Set Device Control 
Block (DCB) (Category 1 Function 53H). 

Note: If the port will not be open any more after processing a 
close request packet (last level close) DTR and RTS will be turned 
OFF (by the device driver). 

After the transmit hardware has completely transmitted (at the 
physical RS232 interface) all the data that it has been given to 
transmit by the device driver and at least 10 additional character 
times have elapsed. 
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Category 1 - 
Function 46H 



Returns 

If the call is made with invalid Parameter Packet values then a 
general failure error Is reported, the modem control signals are not 
changed, and the data packet Information returned to the application 
is undefined. 

Remarks 

None 
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Category 1 - 
Function 47H 



Purpose 

Behave as if XOFF Received (stop transmitting) 

Parameter Packet Format 

None. Packet pointer must be NULL. 

Data Packet Format 

None. Paclcet pointer must be NULL. 

Returns 

If the call is made with invalid Parameter/Data Packet values, a 
general failure error is reported and this request is not performed by 
the device driver. 

Remarks 

If a general failure error is not returned by the device driver, this 
function causes data transmission to be halted by preventing the 
device driver from sending additional data to the transmit hardware. 

If automatic transmit flow control is enabled then this request causes 
the device driver to behave exactly as if it received the XOFF char- 
acter. Transmission can be resumed (due to being stopped from this 
request) when an XON is received by the device driver, when a Cate- 
gory 1 Function 4BH (Behave as if XON received) request is received, 
or when the device driver is told to disable automatic transmit flow 
control and the previous state was that automatic transmit flow 
control was enabled. 

If automatic transmit flow control is disabled then a Category 1 Func- 
tion 48H (Behave as if XON received) request is required for trans- 
mission to be resumed (due to being stopped from this request). If 
after this request is received, the device driver is told to enable auto- 
matic transmit flow control then transmission is still disabled but can 
be re-enabled (due to being stopped from this request) by any of the 
scenarios discussed in the automatic transmit flow control being 
enabled scenario. 
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Category 1 - 
Function 47H 

Note: There still may be other reasons why transmission may be 
disabled. (See Return COM Status, Category 1 Function 64H.) 
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Category 1 - 
Function 48H 



Purpose 

Behave as if XON Received (start transmitting) 

Parameter Packet Format 

None. Paclcet pointer must be NULL. 

Data Packet Format 

None. Paclcet pointer must be NULL. 

Returns 

If the call is made with invalid Parameter/Data Packet values, a 
general failure error is reported and this request is not performed by 
the device driver. 

Remarks 

If a general failure error is not returned by the device driver, this 
function allows data transmission to be resumed by the device driver 
if data transmission is halted due to a Category 1 function 47H 
(Behave as If XOFF received) request or due to an XOFF character 
being received while the device driver is in automatic transmit flow 
control mode. 

Note: There still may be other reasons why transmission may be 
disabled; so transmission may not be resumed. (See Return COM 
Status, Category 1 Function 64H.) 
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Category 1 - 
Function 4BH 




Purpose 

o6t breaK un 




Parameter Packet Format 

iNons. raCKei poinier mUSI D6 inull. 




Data Packet Format 




Field 


Length 


COM Error Word (COMERR) 


WORD 



Where 

COM Error Word 

The device driver returns this Information if a general failure error 
Is not reported. See Category 1 Function 6DH, Return COM Error, 
for COMERR definition. The COM device error information Is not 
cleared by this action. 

A CLOSE request packet, when after processing this close request 
the port will not be open any more (from another open without a 
close) will cause break to be turned off. 

Returns 

If the call Is made with an Invalid Parameter Packet value then a 
general failure error is reported, this function Is not performed and 
valid information Is not returned in the Data Packet. 

Remarks 

If a general failure error is not returned then the device driver will 
perform the following action: 

The device driver will generate the break signal Immediately. It Is 
not considered an error if the device driver is already generating a 
break signal. The device driver will not wait for the transmit hard- 
ware to become empty. Note that more data will not be given to the 
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Category 1 - 
Function 4BH 

transmit hardware until the brealc is turned off The breal< signal will 
always be transmitted, regardless of whether the device driver is or 
is not transmitting characters due to other reasons. 
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Category 1 - 
Function 53H 



Purpose 

Set Device Control Block (DCB) 



Parameter Packet Format 



Field 


Length 


Write Timeout 


WORD 


Read Timeout 


WORD 


Flagsl 


BYTE 


Flags2 


BYTE 


Flags3 


BYTE 


Error Replacement Cliaracter 


BYTE 


Break Replacement Character 


BYTE 


XON Character 


BYTE 


XOFF Character 


BYTE 



Data Packet Format 

None. Packet pointer must be NULL 

Where 

Write Timeout 

specifies the time period used for write timeout processing. The 
value is in .01 second units ( based on 0, where 0 equals .01 
seconds). Refer to Note 8: Write Timeout later in this chapter. 

Read Timeout 

specifies the time period used for read timeout processing. The 
value is in .01 second units ( based on 0, where 0 equals .01 
seconds). Refer to Note 9: Read Timeout later in this chapter. 
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Category 1 - 
Function 53H 



Flagsl: 

Note Bit Meaning 

1 0-1 DTR Control Mode 



Biti 


BitO 




0 


0 


Disable 


0 


1 


Enable 


1 


0 


Input handshaking 


1 


1 


Invalid input resulting in 



general failure 





2 


reserved (set to 0) 


3 


3 


Enable output handshaking using CTS 


3 


4 


Enable output handshaking using DSR 


3 


5 


Enable output handshaking using DCD 


4 


6 


Enable input sensitivity using DSR 




7 


reserved (set to 0) 


Flags2: 




Note 


Bit 


iMeaning 


2 


0 


Enable automatic transmit flow control 






(XON/XOFF) 


2 


1 


Enable automatic receive flow control 






(XON/XOFF) 


5 


2 


Enable error replacement character 


6 


3 


Enable null stripping (remove null bytes) 


7 


4 


Enable break replacement character 




5 


reserved (set to 0) 


1 


6-7 


RTS Control Mode 



Bit? 


B/f6 




0 


0 


Disable 


0 


1 


Enable 


1 


0 


Input handshaking 


1 


1 


Toggling on transmit 
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Meaning 

Enable write infinite time out processing 
Read timeout processing 

Bit 2 Blt1 

0 0 Invalid input resulting In general 
failure 

0 1 Normal read timeout processing 

1 0 Waitfor something, read timeout 
processing 

1 1 No wait, read timeout proc- 
essing 

3 reserved (set to 0) 

4 reserved (set to 0) 

5 reserved (set to 0) 

6 reserved (set to 0) 

7 reserved (set to 0) 

Error Replacement Character 

any byte value in the range OOH to FFH. Refer to Note 5: Error 
Replacement Character later In this chapter. 

Break Replacement Character 

any byte value in the range OOH to FFH. Refer to Note 7: Break 
Replacement Character later in this chapter. 

XON Character 

any byte value In the range OOH to FFH. Refer to Note 2: Auto- 
matic Flow Control later In this chapter. 

XOFF Character 

any byte value in the range OOH to FFH. Refer to Note 2: Auto- 
matic Flow Control later in this chapter. 

Returns 

If the call is made with invalid Parameter/Data Packet values, a 
general failure error Is reported and none of the Device Control Block 
(DCB) characteristics of the device driver for this COM device are 
changed. 
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Note Bit 

8 0 

9 1-2 
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Remarks 

The general Device Control Block (DCB) parameter access functions 
(53H and 73H) are used for: 

• Automatic transmit flow control (start/stop transmit when 
XON/XOFF character received) 

• Automatic receive flow control (transmit XON/XOFF when 
receive buffer fills/empties) 

• Determine XON/XOFF characters 

• DTR control mode (enable/disable/input handshal<ing) 

• RTS control mode (enable/disable/input handshaking/toggling on 
transmit) 

• Output handshaking using CTS/DSR/DCD (control signal deter- 
mines when to transmit) 

• Input sensitivity using DSR (reception of data controlled by DSR) 

• Error replacement character and processing 

• Break replacement character and processing 

• Null stripping 

• Receive/transmit time out processing 

If a general failure error is not returned, the device driver will return 
valid information in the Data Packet. 

The bit fields that are labeled Reserved (returned as 0), will return 
the current value (0) for these bits so a Set Device Control Block ), 
will maintain the current device driver value for these bits. The bits 
defined as such will be returned as 0, but applications should not be 
written to make that assumption. Applications also should not be 
written to assume that the fourth bit combination will never be 
returned for DTR Control Mode or Read Timeout processing. Appli- 
cations should not attempt to manipulate these Reserved bits. 

Note: To maintain upward compatibility, the application should do a 
Return Device Control Block (DCB) information before the Set func- 
tion is used. This will allow the reserved (set to 0) bits to be set cor- 
rectly in a future release of the device driver when these bit positions 
may take on a real meaning. By doing the return first the application 
can maintain the state of the device driver for a mode that the appli- 
cation is not aware of. 
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Note 1: Control of DTR and RTS: The device driver allows the caller 
to automatically control the setting of Data Terminal Ready (DTR) and 
Request To Send (RTS) in many different ways via the RTS Control 
Mode and the DTR Control Mode settings of the Set Device Control 
Block lOCtl. The application can also request manual control over 
these modem control signals. The ways these signals are control- 
lable are as follows: 

Set RTS Control Mode to Toggling on Transmit. 



If bits 7,6 of Flags 2 are set to 1,1 then the device driver is in this 
automatic control mode of RTS. When the device driver is initial- 
ized, the RTS Control Mode is Enable; so initially the device driver 
is not in this automatic control mode of RTS. 

Note: This mode of operation of the device driver should only be 
enabled when the system is attached to devices which will not 
present data to the system receive hardware when RTS is on. 

In this mode, the device driver will: 

• Always turn on RTS if a break is being transmitted. 

• Once data is in the transmit hardware buffer, the device driver 
will not turn RTS off until the transmit hardware has emptied 
its buffers. 

• Turn on RTS (if not already on) if there is data in the device 
driver transmit queue OR if there is an outstanding WRITE 
request packet and: 

— The device driver is allowed to transmit even if automatic 
transmit/receive flow control (XON/XOFF) is enabled. Still 
need to turn on RTS momentarily to transmit a character 
immediate if not normally allowed to transmit due to auto- 
matic transmit/receive flow control (XON/XOFF). 
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— The device driver is allowed to transmit because it was 
not told to behave as if an XOFF had been received (Cate- 
gory 1 Function 47H). The device driver will still need to 
turn on RTS momentarily to transmit a character imme- 
diate if not normally transmitting due to XOFF flow control 
considerations. The device driver will still need to turn on 
RTS momentarily to transmit an XON or XOFF due to auto- 
matic receive flow control if not normally transmitting due 
to XOFF flow control considerations. 

• Turn off RTS (if not already off) if either of the following condi- 
tions are true: 

— No more data in the device driver transmit queue (and no 
more data in WRITE requests in progress), no queued 
WRITE requests, and the transmit hardware has physically 
transmitted (at the physical RS232 interface) all the data 
that it has been given. 

— The device driver is not allowed to transmit due to 
transmit/receive flow control (XON/XOFF) being enabled 
or due to being asked to behave as if an XOFF had been 
received (Category 1 Function 47H). The device driver 
still needs to turn on RTS to transmit a character imme- 
diate or XON/XOFF due to automatic receive flow control 
(XON/XOFF). RTS is never turned off until the transmit 
hardware has physically transmitted (at the physical 
RS232 interface) all the data that it has been given. 

• When this function is enabled, the device driver will control 
RTS appropriately, as determined by the above description. 

• If this function is disabled (by choosing a new RTS Control 
Mode), then RTS will be controlled appropriately by the new 
RTS Control Mode that is inherently chosen when this RTS 
Control Mode is disabled. 

• The device driver will NOT examine any other modem control 
signals before It turns RTS off or on. 

An OPEN request packet will not cause the device driver to 
change the RTS Control Mode that the device driver is in. The 
device driver will maintain the state of this mode of operation 
across OPEN request packets. 
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When the device driver is in the RTS Control Mode toggling on 
transmit, then the device driver will not allow the application to 
control RTS by the Set Modem Control Signals (Category 1 Func- 
tion 46H). 

Set DTP and/or RTS Control Mode to Input Handshaking. 

Setting bits 1,0 of Flags 1 to 1,0 sets the DTR Control Mode to 
Input Handshaking. Setting bits 7,6 of Flags 2 to 1,0 sets the RTS 
control mode to Input Handshaking. When the device driver is ini- 
tialized, the RTS and DTR Control Mode is Enable; so initially the 
device driver is not in this automatic control mode of RTS and 
DTR. 

Note: This mode of operation of the device driver should only be 
set when there is the possibility of a device driver RECEIVE 
QUEUE overrun and the system is attached to data terminal equip- 
ment which will stop transmitting data when the appropriate 
modem control signals are turned off, due to the cabling and the 
data terminal equipment characteristics. 

Because Input Handshaking mode can be set for either RTS or 
DTR or both, the DTR and RTS Control Modes are processed Inde- 
pendently. 

In Input Handshaking mode the device driver will: 

• Turn the appropriate modem control signal(s) ON when the 
device driver receive queue is less than about half full. 

• Turn the appropriate modem control slgnal(s) OFF when the 
device driver receive queue gets close to full. 

• When this mode is first set, the device driver will not monitor 
the value of the appropriate modem control signal (s) (DTR or 
RTS) when the queue size Is between approximately half full 
and almost full. 

• When this function is enabled, the device driver will determine 
the correct value of the modem control signal (s) and control 
them accordingly. 

• If this function is disabled (by choosing a new RTS and/or DTR 
Control Mode), RTS and/or DTR will be controlled appropri- 
ately by the new RTS and/or DTR Control Mode that is inher- 
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ently chosen when this RTS and/or DTR Control Mode Is 
disabled. 

• The device driver will NOT examine any other modem control 
signals before controlling DTR or RTS due to this mode. 

An OPEN request packet will not cause the device driver to 
change the RTS and DTR Control Modes that the device driver is 
In. The device driver will maintain the state of these modes of 
operation across OPEN request pacicets. 

When the device driver is in the RTS Control Mode Input Hand- 
shaking then the device driver will not allow the application to 
control RTS via Set Modem Control Signals (Category 1 Function 
46H). When the device driver is In the DTR Control Mode Input 
Handshaking, then the device driver will not allow the application 
to control DTR via Set Modem Control Signals (Category 1 Func- 
tion 46H). 

Set DTR and/or RTS Control Mode to Enable or Disable. 
OPEN processing 

• Setting bits 1,0 of Flags 1 to 0,0 sets the DTR Control Mode 
to Disable. 

• Setting bits 1,0 of Flags 1 to 0,1 sets the DTR Control Mode 
to Enable. 

• Setting bits 7,6 of Flags 2 to 0,0 sets the RTS control mode 
to Disable. 

• Setting bits 7,6 of Flags 2 to 0,1 sets the RTS control mode 
to Enable. 

When the device driver is initialized, the RTS and DTR Control 
Mode is Enable, but the value of the modem control signals is 
OFF until the port gets an OPEN request packet. 

An OPEN request packet will not cause the device driver to 
change the RTS and DTR Control Modes that the device driver 
is in. The device driver will maintain the state of these modes 
of operation across OPEN request packets. 

Because Enable or Disable modes can be set for either RTS or 
DTR or both, the DTR and RTS Control Modes are processed 
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independently. The following discussion covers what happens 
to RTS. The same discussion also applies to DTR if the DTR 
Control Mode Is set as described In the RTS discussion. 

If the RTS Control Mode is Disable, when the device driver 
receives an OPEN request packet and the device is not already 
open (from a previous open without a close - First Level Open), 
the RTS modem control signal will be kept (turned) OFF during 
the OPEN processing. If the RTS Control Mode is Enable then 
when the device driver receives an OPEN request packet and 
the device is not already open (from a previous open without a 
close - First Level Open), the RTS modem control signal will be 
turned ON during the OPEN processing. 

If the RTS Control Mode is set to Disable and the previous 
mode was not Disable, the RTS modem control signal Is turned 
OFF. If the RTS Control Mode is set to Disable and the pre- 
vious mode was also Disable, this lOCtI has no effect on the 
RTS modem control signal. 

If the RTS Control Mode is set to Enable and the previous 
mode was not Enable, the RTS modem control signal Is turned 
ON. If the RTS Control Mode is set to Enable and the previous 
mode was also Enable, this lOCtI has no effect on the RTS 
modem control signal. 

The following summarizes the previous discussion: 
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DTR/RTS: 

(IH= Input Handshaking) 
FROM(l) T0(1) EFFECT(2) 



Disable Disable none 
Disable Enable turn ON 
Disable IH auto(3) 

Enable Disable turn OFF 
Enabl e Enabl e none 
Enable IH auto (3) 

IH Disable turn OFF 
IH Enable turn ON 
IH IH auto(3) 

RTS ONLY: 

(toggle = toggle on transmit) 

Disable toggle auto(4) 
Enable toggle auto (4) 
IH toggle auto(4) 

toggle Disable turn OFF 

toggle Enable turn ON 

toggle IH auto(3) 

toggle toggle auto (4) 

(1) - From or To Control Mode. 

(2) - Effect on the modem control signal. 

(3) - Modem control signal controlled automatically (See the 
section on Input Handshaking). 

(4) - Modem control signal controlled automatically (See the 
section on Toggling on Transmit). 

Because the initial Control Mode of the device driver is Enable 
for RTS and DTR, both modem control signals will be turned 
ON when the port is first opened. 

If the device driver receives an OPEN request packet and the 
device is already open, the device driver does not alter the 
value of the RTS and DTR modem control signals, regardless 
of the Control Mode. 
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Application control of DTR and RTS. 

The application can explicitly turn DTR or RTS ON or OFF 
(independently) with the Set Modem Control Signals lOCti (Cat- 
egory 1 Function 46H). 

If the Control Mode of RTS is not Enable or Disable, the appli- 
cation may not control RTS with the Set Modem Control 
Signals lOCtI because the device driver is controlling the 
signal automatically (toggling on transmit or input hand- 
shaking). If the Control Mode of DTR is not Enable or Disable, 
the application may not control DTR with the Set Modem 
Control Signals lOCtI because the device drive is controlling 
the signal automatically (input handshaking). 

CLOSE processing. 

If the device driver receives a CLOSE request packet and the 
COM device will still be open (from another open without a 
close) then the device driver will not change the values of DTR 
or RTS. 

If the device driver receives a CLOSE request packet, when 
after processing this close request the port will not be open 
any more (from another open without a close - Last Level 
Close) then, at the end of the CLOSE processing, RTS and DTR 
will be turned OFF by the device driver; after waiting the 
appropriate amount of time- (See description of CLOSE proc- 
essing and lOCti Set Modem Control Signals, Category 1 Func- 
tion 46H). 
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Note 2: Automatic Flow Control. XON/XOFF Characters: If bit 0 of 

Flags 2 Is set, the device driver is enabled for automatic transmit flow 
control. If bit 1 is set, the device driver Is enabled for automatic 
receive flow control. 

When the device driver is initialized these bits are reset, so initially 
the device driver Is not enabled for automatic transmit or receive flow 
control. 

An OPEN request packet will not cause the device driver to change 
the enabling or disabling state of automatic transmit/receive flow 
control. 

An OPEN request packet, when the COM device is not already open 
(from a previous open without a close - First Level Open), will cause 
the device driver to believe It has not received an XOFF if automatic 
transmit flow control is enabled and will cause the device driver to 
believe it has not transmitted an XOFF if automatic receive flow 
control Is enabled. 

Automatic Transmit Flow Control (XON/XOFF) 

In the discussion that follows it is stated in places that the device 
driver will transmit XON or XOFF. There are reasons why the device 
driver may not be able to transmit an XON or XOFF (transmitting 
break, Invalid output handshaking on modem control signals). It is 
also stated that the device driver will resume transmitting data. 
There are also other potential reasons (not related to automatic 
transmit/receive flow control) why that may not be possible. See 
Return COM Status lOCtI (Category 1 Function 64H). 

When XON and XOFF flow control during transmission Is enabled, the 
device driver will stop sending data to the transmit hardware when an 
XOFF is received, and resume sending data to the transmit hardware 
when an XON Is received. (Reminder: Transmission may not be pos- 
sible due to other reasons). The device driver will still transmit char- 
acters due to the transmit immediate request lOCtI (Category 1 
Function 44H). The device driver will still transmit XON and XOFF 
due to automatic receive flow control. 
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When the device driver is in this mode, it will not pass received XON 
and XOFF characters to the application. Instead, the device driver 
will act upon receiving those characters and throw them away. 

The device driver may transmit additional characters before it recog- 
nizes an XOFF character which it has not read but which may be in 
the receive buffer of the hardware. The extent of this scenario will be 
minimized, but the combined transmit/receive Advanced BIOS 
request block will still be used on systems that support Advanced 
BIOS. If the system is relatively slow in responding to interrupts com- 
pared to the current baud rate, receive buffer overruns may not be 
occurring, but the device driver may be apparently slow in 
responding to an XOFF character. 

If automatic transmit flow control is disabled (after currently enabled) 
and transmission was not occurring due to an XOFF being received or 
lOCtI Category 1 Function 47H (behave as if XOFF received) being 
requested, then transmission will be resumed. (Reminder: trans- 
mission may not be resumed for other reasons.) 

See States of the RS232 device driver for the effect of OPEN request 
packets on this mode of the device driver. It is the application's 
responsibility not to fully close the port in a way that will cause the 
device driver to Illegally transmit characters when the port is 
re-opened after being fully closed (First Level Open). 

Output handshaking using modem control signals Is another way that 
the device driver can be told to stop transmitting. See Note 3. 

Automatic Receive Fiow Controi (XON/XOFF) 

When XON and XOFF flow control during receive is enabled, the 
device driver will transmit an XOFF when its receive queue gets close 
to full, and an XON when its receive queue is about half full. After the 
XOFF is sent, the COM device driver will send no characters until it 
sends an XON due to automatic receive flow control. This is to 
accommodate those systems that interpret the first character 
received after an XOFF as an XON, regardless of what the character 
actually is. The device driver will still transmit characters due to the 
transmit immediate request (Category 1 Function 44H). 
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The device driver will not be able to transmit an XOFF or XON if it is 
transmitting a break. Tlie device driver will not be able to automat- 
ically transmit an XOFF or XON if it is enabled for output hand- 
sliaking, with certain modem control signals, and those modem 
control signals are not ON. This could cause a deadlock if the device 
driver wishes to transmit an XON and it cannot. The device driver 
will remember that it wanted to transmit an XOFF or XON and will still 
do so when transmit conditions permit; assuming the receive queue 
conditions still warrant it. 

The device driver will not monitor characters being transmitted by 
WRITE request packets to see if any of them are XON or XOFF. The 
device driver will also not monitor characters transmitted imme- 
diately (Category 1 Function 44H). For example, the device driver 
will not stop transmitting characters if the application causes the 
device driver to explicitly transmit an XOFF. 

If automatic receive flow control is enabled (after currently disabled), 
the device driver will immediately check the receive queue level to 
see if an XOFF needs to be transmitted. An XON is never transmitted 
immediately due to this function being enabled. The device driver 
will only automatically transmit an XON character after it has auto- 
matically transmitted an XOFF character. 

If automatic receive flow control is disabled (after currently enabled), 
and transmission was not occurring due to an XOFF being automat- 
ically transmitted, the device driver will transmit an XON and trans- 
mission will be resumed if possible. (Reminder: transmission may 
not be taking place for other reasons.) 

If the device driver previously automatically transmitted an XOFF, and 
a CLOSE request packet is received, when after processing this close 
request the port will not be open any more (from another open 
without a close), the device driver will automatically transmit an XON 
if possible. 

See states of the device driver for the effect of OPEN request packets 
on this mode of the device driver. It is the application's responsibility 
not to fully close the port in a way that will cause the device driver to 
illegally transmit characters or the communications link to be in a 
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deadlock state when the port is re-opened after being fully closed 
(First Level Open). 

Input handshaking using modem control signals is another way that 
the device driver can tell another device to stop transmitting. See 
Note 1. 

XON and XOFF CHARACTERS 

The value of these bytes in the device control block determine the 
value of the XON and XOFF character that is used for automatic 
transmit and receive flow control. 

When the XON and XOFF characters are referred to in the Category 1 
lOCtI section, the reference is to the value of the XON and XOFF char- 
acter as determined by this lOCtl. 

When the device driver is first initialized, the XON character is 11H 
and the XOFF character is 13H. An OPEN request packet, when the 
COM device is not already open, (from a previous open without a 
close - First Level Open), will cause the XON character to be set to 
111-1 and the XOFF character to be set to 13H. 

If the XON and XOFF characters are set equal with this lOCtI, the 
results are UNDEFINED. 

Note 3: Output Handshaking Using GTS, DSR, DCD.: Bits 3, 4, and 5 of 
Flags 1 control output handshaking using CTS, DSR, and DCD respec- 
tively, if the bit is set, output handshaking for the appropriate modem 
control signal is enabled. 

Output Handshaking mode can be enabled for any combination of 
CTS, DSR, or DCD because bit 3, 4, and 5 of Flags 1 are processed 
independently. 

When the device driver is initialized, bits 3 and 4 of Flagsl are set 
and bit 5 of Flagsl is reset; Therefore, so initially the device driver is 
enabled for output handshaking using CTS and DSR but disabled for 
output handshaking using DCD. 
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Except for attachment to special devices and/or special cables, output 
handshaking using DCD should not be enabled. 

Disabling output handshaking using CTS and/or DSR will cause unex- 
pected results when the system is attached to data terminal devices 
or data communications devices that toggle CTS and/or DSR in order 
to control the ability of the system to transmit data. 

If the device driver is enabled for this mode of operation, the device 
driver will be affected in the following manner if the appropriate 
modem signal(s) are OFF: 

• The device driver will be unable to move data from the device 
driver transmit queue to the transmit hardware. 

• The device driver will be unable to transmit a character imme- 
diately (Category 1 Function 44H) so the character Is remembered 
by the device driver. 

• The device driver will be unable to automatically transmit XONs 
and XOFFs. The device driver may wish to transmit XONs and 
XOFFs as a result of automatic receive flow control being 
enabled. 

• The device driver will still generate a break immediately if 
requested. 

• The value of CTS, DSR, and DCD do not affect how the device 
driver controls RTS and DTR. 

An OPEN request packet will not cause the device driver to change 
the value of bits 3, 4, and 5 of Flags 1. The device driver will maintain 
the state of this mode of operation across OPEN request packets. 

On devices with a transmit holding register and transmit shift reg- 
ister, the transmit holding register will always be given another char- 
acter to transmit when It empties (even though a character may still 
be in the transmit shift register), unless the device driver determines 
that is not allowed to transmit any more. 

The device driver will always attempt to detect a change in the 
modem status signals (CTS, DSR, DCD) before transmitting more 
data. This requires bypassing the natural priority of the current 
ASYNC hardware and requires additional complexity in the Advanced 
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BIOS implementation. This feature prevents a temporary elongation 
of interrupt latency from not allowing the device driver to recognize a 
change in a modem control signal. (The modem control signal 
change happened many character times before the transmit hard- 
ware is requesting that another character be given to it). 

Note 4: Input Sensitivity Using DSR.: Bit 6 of Flags 1 controls input 
sensitivity using DSR. if the bit is set, input sensitivity using DSR is 
enabled. 

When the device driver is initialized, bit 6 of Flags 1 is set; so initially 
the device driver is enabled for input sensitivity using DSR. 

Note: Disabling input sensitivity using DSR will cause unexpected 
results when the system is attached to data terminal devices or data 
communications devices that toggle DSR when they generate spu- 
rious data that they do not wish the system to receive. 

If the device driver is enabled for this mode of operation, the device 
driver will throw away all data input from the receive hardware if DSR 

is off. 

If the device driver processes a change In the DSR modem control 
signal from ON to OFF or OFF to ON at the same time that it inputs a 
character from the receive hardware, the device driver will still 
accept that last character(s). This will prevent a temporary 
elongation of interrupt latency from causing the device driver to 
discard a valid character(s). However this could cause the device 
driver to attempt to process invalid data for one service period of the 
receive hardware. This requires that the change in the modem 
control signal gets processed before the device driver attempts to 
receive data from the receive hardware (See Note 3); or that the 
received data is saved until a change in modem status (during the 
same hardware service Instance) can be determined. 

An OPEN request pacl<et will not cause the device driver to change 
the value of bit 6 of Flags 1. The device driver will maintain the state 
of this mode of operation across OPEN request packets. 
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Note 5: Error Replacement Character: Bit 2 in Flags 2 controls the 
enabling of error replacement character processing. If the bit is set, 
the error replacement character processing is enabled. 

When the device driver Is Initialized this bit is reset, so initially the 
device driver is not enabled for the error replacement character. An 
OPEN request packet, when the COM device is not already open 
(from a previous open without a close - First Level Open) will cause 
this bit to be reset, disabling error replacement character processing. 

When the device driver is Initialized, the error replacement character 
Is OOH. An OPEN request packet, when the COM device is not already 
open (from a previous open without a close) will cause the error 
replacement character to be set back to a OOH. 

If error replacement character processing is disabled, the following 
applies: 

• If a parity or framing error occurs and if the character that had 
the error is available in the receive hardware buffer, it is placed 
In the device driver receive queue. 

• If a hardware or receive queue overrun occurs then nothing 
special is placed in the receive queue to designate an overrun. 

If error replacement character processing Is enabled, the following 
applies: 

• If a parity or framing error occurs, the error replacement char- 
acter is placed In the device driver receive queue. (The char- 
acter in the receive hardware buffer. If It was available, Is not 
placed in the receive queue.) 

• If a hardware buffer overrun occurs, the error replacement char- 
acter is placed in the device driver receive queue to mark the 
position that a receive overrun occurred. If valid data is in the 
receive hardware buffer, it is still placed in the device driver 
receive queue. The processing of the valid data takes place after 
the hardware buffer overrun condition Is recorded in the device 
driver receive queue. 

• If a device driver receive queue overrun occurs, the last char- 
acter in the receive queue is replaced with the error replacement 
character. This allows the application to know the position of 
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where the error occurred. This error replacement (If enabled) 
will always take precedence over an error replacement or break 
replacement event that occurred at the same character time. 

Regardless of whether error replacement character processing is 
enabled, null stripping and checking for XON/XOFF characters will 
not occur if the character had an error. 

This lOCtI can be used to change the error replacement character by 
changing the byte representing the error replacement character. 

Note 6: Null Stripping: Bit 3 in Flags 2 controls the enabling of null 
stripping processing. If the bit is set, null stripping processing is 
enabled. 

When the device driver is initialized this bit is reset, so initially the 
device driver is not enabled for null stripping. An OPEN request 
packet, when the COM device is not already open (from a previous 
open without a close - First Level Open) will cause this bit to be reset; 
disabling null stripping. 

If the device driver is enabled for null stripping when characters are 
read in from the receive hardware any (non error or non break) char- 
acters with a value of OOH are thrown away, are not checked even if 
the XON or XOFF character has been set to OOH, and are not placed In 
the device driver receive queue. 

Note: Simultaneously setting the XON or XOFF character to OOH, ena- 
bling automatic transmit flow control, and enabling null stripping may 
cause unexpected results but is not considered an error condition by 
the device driver error checking logic. 

Note 7: Break Replacement Character: Bit 4 in Flags 2 controls the 
enabling of break replacement character processing. If the bit is set, 
the break replacement character processing is enabled. 

When the device driver is initialized this bit is reset, so initially the 
device driver is not enabled for the break replacement character. An 
OPEN request packet, when the COM device is not already open 
(from a previous open without a close - First Level Open) will cause 
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this bit to be reset, disabling break replacement character proc- 
essing. 

When the device driver is initialized, the break replacement character 
is OOH. An OPEN request packet, when the COM device is not already 
open (from a previous open without a close - First Level Open) will 
cause the break replacement character to be reset back to a OOH. 

If break replacement character processing is disabled, the device 
driver will not place any character in the device driver receive queue 
when it detects a break condition on the line. A detected break condi- 
tion has no effect on XON/XOFF detection. 

If break replacement character processing is enabled, when the 
device driver detects a break condition, it will place the break 
replacement character in the device driver receive queue. 

If break replacement character processing is enabled, null stripping 
and checking for XON/XOFF characters will not operate on the break 
replacement character. 

This lOCtI can be used to change the break replacement character by 
changing the byte representing the break replacement character. 

If a parity or framing error is generated due to the reception of a 
break, error replacement processing is not done (except for the 
overrun condition), break replacement processing is done. 

Note 8: Write Timeout: Bit 0 in FlagsS controls the characteristics of 
Write timeout processing. If the bit is 0, Write timeout processing 
uses the value in the Write Timeout word in the device control block. 
If the bit is 1, Write timeout processing is infinite time out. 

The value in the Write Timeout word is in .01 second units (based on 
0 where, 0 = .01 seconds). The device driver is considered doing 
normal write timeout processing when the Write Timeout word is 
used for write timeout processing. 

During normal write timeout processing, if the device driver does not 
give ANY data to the transmit hardware (from the transmit queue) 
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within the period of time specified by the Write Timeout word (due to 
some reason that prevents the device driver from transmitting data), 
the request wili be completed. The accuracy of the time out period 
MAY be determined by the request packet being blocked in the 
device driver and how long it takes for the thread to be dispatched 
once it is made ready by the time out period expiring; OR the accu- 
racy of the time out period MAY be determined by the accuracy of the 
device driver timer tick processing. If any data had been given to the 
transmit hardware in that time out period, the specified period of time 
will be waited for again, to see if any more data had been trans- 
mitted. 

If the time out period Is changed by this lOCtI (or to infinite time out), 
the new time may take effect immediately or may take effect after the 
next character is written. 

During write infinite time out processing, the request will not com- 
plete until all the data from the request has been given to the transmit 
hardware. The thread of the Write request will not return to the 
system until the request completes. The device driver will check to 
see if an lOCtI has changed the write timeout processing character- 
istics at least every minute. This could occur almost Immediately 
(accuracy MAY be determined by the request packet being blocked 
and/or by device driver timer ticks). This will insure that the device 
driver periodically checks to see if write infinite time out processing 
had been changed to normal write timeout processing. 

As discussed above, the write timeout characteristics can be changed 
in the middle of the processing of a write request and the new time 
out attributes is guaranteed to eventually take effect. 

When the device driver Initializes, normal write timeout processing is 
in effect. 

When the device driver receives an OPEN request packet for the port 
and the port is not already open (from a previous open without a 
matching close - First Level Open), the value In the write timeout 
word is set to 1 minute. The current write timeout processing charac- 
teristics (normal or infinite) is not affected. 
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Note 9: Read Timeout: Bits 2, 1 of flags 3, control the Read timeout 
processing characteristics of the device driver. The three possible 
types of Read timeout processing are: 

• Normal (Bits 2,1= 0,1) 

• Wait For Something (Bits 2,1 = 1,0) 

• NO WAIT (Bits 2,1 = 1,1) 

The value in the Read Timeout word is in .01 second units (based on 
0, where 0 = .01 seconds). The device driver uses the value in the 
Read timeout word for Normal and Wait For Something Read timeout 
processing. The accuracy of the time interval MAY be determined by 
the request being blocked In the device driver and/or by device driver 
timer ticlcs. 

However, in the following two cases (of data being received), the 
current interval of time will continue to be waited on without starting 
to wait from the beginning of the interval again: 

1. if input sensitivity using DSR is ENABLED and the value of the 
DSR modem control signal causes input data to be thrown away. 
Refer to Note 4: Input Sensitivity using DSR earlier in this 
chapter. 

2. if null stripping is ENABLED and a null character is stripped. 
Refer to Note 6: Null Stripping earlier in this chapter. 

If the device driver is doing Normal Read time out processing, the 
device driver will wait as long as the value in the Read timeout word 
says to wait. The request will be completed after that interval of time 
elapses, if no more data has been received for the request, if any 
data is received by the device driver (from the receive hardware) for 
the request (including XON/XOFF characters), the specified period of 
time will be waited on again (for more data to arrive). 

If the device driver Is doing NO WAIT read timeout processing, the 
device driver will not wait for any data to be available in the receive 
queue. When the device driver begins to try to move data from the 
receive queue to the request, the request will complete. Whatever 
data is available in the receive queue at that time is the amount of 
data that will be moved to the request. 
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If the device driver is doing Wait For Something read timeout proc- 
essing, the device driver will process the request initially as if it had 
no wait time out processing, if no data was available at the time the 
request would have completed due to NO WAIT processing, the 
request is not completed. Instead, the request waits for some data to 
be available before completing the request. However, the device 
driver does enter Normal read timeout processing for this request. 
Therefore, if no data is available after the Normal timeout processing 
interval then the request will be completed anyway. The request will 
never wait any longer then it would have due to Normal read timeout 
processing. 

The read timeout processing characteristics that apply to a given 
read request is not determined until the device driver begins proc- 
essing that request. Once the device driver begins processing that 
request, a change to the read timeout processing characteristics of 
the device driver between Wait For Something and Normal time out 
processing may or may not take effect for the current read request 
being processed. If the time out period is changed by this lOCtI, the 
new time out period may take effect immediately, or it may take effect 
after the next character is received from the receive hardware. 

When the device driver initializes, normal read timeout processing is 
in effect. 

When the device driver receives an OPEN request packet for the port 
and the port is not already open (from a previous open without a 
matching close - First Level Open), the value in the write timeout 
word is set to 1 minute and normal read timeout processing charac- 
teristics is put into effect. 
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Purpose 

Return Baud (bit) Rate 




Parameter Packet Format 

None. Packet pointer must be NULL. 




Data Packet Format 




Field 


Length 


Bit Rate 


WORD 



Where 

Bit Rate 

Tlie binary integer representing the actual baud (bit) rate of the 
COM device in bits per second. 

Returns 

If the call is made with an invalid Parameter Packet value then a 
general failure error is reported and valid information is not returned 
in the Data Packet. 

Remarks 

If a general failure error is not returned then the device driver wilt 
return the current baud (bit) rate of the COM device. 



6-47 



Category 1 - 
Function 62H 



Purpose 

Return Line Characteristics (stop bits, parity, data bits, breal<) 



farafficicr raCKel rOrlTlal 

None. Paci<:et Pointer must be NULL. 




Data Packet Format 




Field 


Length 


Data Bits 


BYTE 


Parity 


BYTE 


Stop Bits 


BYTE 


Transmitting Brealc 


BYTE 



Where 

Data Bits 

See set function 42H (Set Line Characteristics) 
Parity 

See set function 42H (Set Line Characteristics) 
Stop Bits 

See set function 42H (Set Line Characteristics) 

Transmitting Srea/r 

0 means not currentiy transmitting breait. 1 means currently trans- 
mitting brealc. 

Returns 

If the call is made with an invalid Parameter Pacl<et value then a 
general failure error is reported and valid information is not returned 
in the Data Packet. 
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Remarks 

If a general failure is not returned, the device driver will return the 
line characteristics as defined. 
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Purpose 

Return COM Status 




Parameter Packet Format 

None. Packet pointer must be NULL. 




Data Packet Format 




Field 


Length 


COM Status Byte 


BYTE 



Where 

COM Status Byte 

1 The condition is true 
0 The condition is faise 



Note 


Bit 


Meaning 


3 


0 


Tx waiting for CTS to be turned ON 


3 


1 


Tx waiting for DSR to be turned ON 


3 


2 


Tx waiting for DCD to be turned ON 


1 


3 


Tx waiting because XOFF received 


2 


4 


Tx waiting because XOFF transmitted 


5 


5 


Tx waiting because breal< being transmitted 


6 


6 


Character waiting to transmit immediately 


4 


7 


Receive waiting for DSR to be turned ON 



Tx (transmit) status indicates why we may not be transmitting; 
regardless of whether there is data to transmit. However the 
device driver must be enabled for the given condition (for 
example, enabled for output handshaicing for the modem control 
signal in question) for the status to reflect that the device driver 
would be waiting for the given condition to transmit. 

For example, 00000001 means the device driver will put receive 
characters in the device driver receive queue, the device driver is 
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not waiting to transmit a cliaracter Immediately (Category 1 Func- 
tion 44H), and we will not transmit characters from the device 
driver transmit queue because we are using CTS for output hand- 
shaking and CTS does not have the proper value. 

Note: 

1. This occurs because the proper conditions when the device 
driver Is enabled for automatic transmit flow control 
(XON/XOFF), or the device driver is not enabled for automatic 
transmit flow control (XON/XOFF) and the device driver Is told 
to behave as If an XOFF had been received (Category 1 Func- 
tion 47H). 

Characters will still be transmitted Immediately (Category 1 
Function 44H) and the device driver can still automatically 
transmit XONs and XOFFs because of automatic receive flow 
control (XON/XOFF) when the device driver Is In this state. 

2. This is because of the proper conditions when the device 
driver Is enabled for automatic receive flow control. 

Characters will still be transmitted Immediately (Category 1 
Function 44H) and the device driver can still automatically 
transmit XONs because of the automatic receive flow control 
when the device driver is in this state. 

3. See Set Device Control Block Note 3 (Category 1 Function 
53H). 

4. See Set Device Control Block Note 4 (Category 1 Function 
53H). 

5. See Set break on (Category 1 Function 4BH). 

6. See Transmit Byte Immediate (Category 1 Function 44H). 

Returns 

If the call is made with an invalid Parameter Packet value a general 
failure error Is reported, and valid information Is not returned in the 
Data Packet. 

Remarks 

If a general failure error is not returned the device driver will return 
the COM device current status. 
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Purpose 

nCiUI II II Qi lOI 1 III LyCllCl WLCILUO 




Parameter Packet Format 

KInno Paplcot Pninter miict ho Nl il 1 




Data Packet Format 




Field 


Length 


Transmit Status 


BYTE 



Where 

Transmit Status 

Is returned as bit significant values. If the bit is 1, the condition is 
true. The bit is 0 if the condition is false. The number at the 
beginning of the description is the bit position number. The bit 
positions go from least to most significant. 

0 - WRITE request packets In progress or queued. 

1 - Data in the device driver transmit queue. 

2 - The transmit hardware is currently transmitting data. 

3 - Character waiting to be transmitted immediately. 

4 - Waiting to automatically transmit an XON. 

5 - Waiting to automatically transmit an XOFF. 

6 - undefined 

7 - undefined 

Returns 

If the call is made with an invalid Parameter Packet value a general 
failure error is reported and valid information is not returned in the 
Data Packet. 
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Remarks 

If a general failure error Is not returned the device driver will return 
the current transmit status of the COM device. 
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Purpose 

Return Modem Control Output Signals 




Parameter Packet Format 

None. Packet pointer must be NULL. 




Data Packet Format 




Field 


Length 


Modem Control Output Signals 


BYTE 


Where 




Modem Control Output Signals 





A bit value of 1 means the condition is ON. A bit value of 0 means 
the condition is OFF. 

Bit Meaning 

0 Data terminal ready (DTR) 

1 Request to send (RTS) 

2 to 7 Undefined 



Returns 

If the call is made with an invalid Parameter Pacl<et value a general 
failure error is reported and valid Information Is not returned In the 
Data Packet. 

Remarks 

If a general failure error is not returned, the device driver will return 
the current modem control output signals of the COM device. 



6-54 



Category 1 - 
Function 67H 



Purpose 

Return Current Modem Control Input Signals 



Parameter Packet Format 


Field 


Length 


Modem Control Input Signals 


BYTE 


Data Packet Format 




None. Packet pointer must be NULL. 





Where 

Modem Control Input Signals 

A bit value of 1 means the condition is ON. A bit value of 0 means 
that the condition is OFF. 



Bit 


Meaning 


0to3 


Undefined 


4 


Clear To Send (CTS) 


5 


Data Set Ready (DSR) 


6 


Ring Indicator (Rl) 


7 


Data Carrier Detect (DCD) 



Returns 

If the call is made with an invalid Parameter Packet value a general 
failure error is reported and valid information is not returned in the 
Data Packet. 

Remarks 

if a general failure error is not returned, the device driver will return 
the current modem control input signals of the COM device. 
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Purpose 

Return Number of Characters in the Receive Queue 


Parameter Packet Format 

None. Pacitet pointer must be NULL 




Data Packet Format 




Field 


Length 


Number of Characters Queued 


WORD 


Size of Receive Queue 


WORD 



Where 

Number of Characters Queued 

Binary integer with the number of received characters in the 
device driver receive queue. The device driver receive queue is a 
memory buffer In between the memory pointed to by the READ 
request pacl<et and the receive hardware for this COM device. 
The appilcation may not assume that there are no unsatisfied 
READ requests if there are characters in the device driver receive 
queue. The behavior of data movement between the READ 
request and the receive queue may change from release to 
release of the device driver. Applications should not be written to 
have a dependency on this information. 

Size of Receive Queue 

Binary integer with the size of the device driver receive queue. 
Applications should be written to be independent of the receive 
queue being of a fixed size. The information in this field allows 
the application to get the size of the receive queue. The current 
size of the receive queue is approximately 1K bytes but is subject 
to change. 

Using this information, the application could be written to avoid 
device driver receive queue overruns. This could be done by 
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using an application to application block protocol with the system 
that the application is communicating with. 

Returns 

If the call is made with an invalid Parameter Packet value, a general 
failure error is reported and valid information is not returned in the 
Data Packet. 

Remarks 

If a general failure error is not returned, the device driver will return 
the information. 
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Purpose 

Return Number of Characters in Transmit Queue 


Parameter Packet Format 




None. Packet pointer must be NULL. 




Data Packet Format 




Field 


Length 


Number of Characters Queued 


WORD 


Size of Transmit Queue 


WORD 



Where 

Number of Characters Queued 

Binary integer with the number of characters ready to be trans- 
mitted in the device driver transmit queue. The device driver 
transmit queue Is a memory buffer between the memory pointed 
to by the WRITE request pacl<et and the transmit hardware for this 
COM device. If the transmit queue is empty, the application may 
not assume that all WRITE requests have completed or that no 
WRITE requests are outstanding. The behavior of data movement 
between the WRITE request and the transmit queue may change 
from release to release of the device driver. Applications should 
not be written to be dependent on this information. 

Size of Transmit Queue 

Binary integer with the size of the device driver transmit queue. 
Applications should be written to be independent of the transmit 
queue being of a fixed size. The information in this field allows 
the application to get the size of the transmit queue. The size of 
the transmit queue is 128 bytes. Applications should not be 
written to have a dependency on this value as it is subject to 
change. 
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Returns 

If the call is made with an invalid Parameter Packet value, a general 
failure error is reported and valid information is not returned in the 
Data Packet. 

Remarks 

If a general failure error is not returned, the device driver will return 
the information. 
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Purpose 

Return COM Error (retrieve and then clear the COM device error 



information) 




Parameter Packet Format 

None. Pacl^et pointer must be NULL. 




Data Packet Format 




Field 


Length 


COM Error Word (COMERR) 


WORD 



Where 

COM Error 

The appropriate bits in the CO.M Error Word are set by the device 
driver when the events described below occur. The COM error 
word is not cleared unless this function is performed by the device 
driver or an OPEN request packet is received by the device driver 
and the COM device is not already open (from a previous open 
without a close first level open). See Note 6 of Set Device Control 
Block (Category 1 Function 53H). 

Bit Meaning 

0 Receive queue overrun. No room in the device driver 
receive queue to put a character read in from the 
receive hardware. 

1 Receive hardware overrun. A character was not read 
from the hardware before the next character arrived 
causing a character to be lost. 

2 The hardware detected a parity error. 

3 The hardware detected a framing error. 

4 to 15 Undefined 
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Returns 

If the call is made with an invalid Parameter Pacl<et value, a general 
failure error is reported, valid information is not returned in the Data 
Packet, and the COM error word Is not cleared. 

Remarks 

If a general failure error is not returned, the device driver will return 
and clear the COM device error Information. 
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Purpose 

Return COM Event Information (retrieve and tlien clear the COM 
device event word) 



Parameter Packet Format 

None. Pacl<et pointer must be NULL. 




Data Packet Format 




Field 


Length 


COM Event Word 


WORD 



Where 

COM Event Word 

The appropriate bits in the COM Event Word are set by the device 
driver when the following events occur: 

Note: The COM Event Word is not cleared unless this function is 
performed by the device driver or an OPEN request packet is 
received by the device driver and the COM device is not already 
open (from a previous open without a close) (first level open). 

Bit Meaning 

0 Set when any character is read from the COM device 
receive hardware and placed in the receive queue. 

1 Undefined 

2 Set when the last character in the device driver transmit 
queue is sent to the COM device transmit hardware. 
This does not mean that there is no data to send in any 
outstanding WRITE requests. 

3 Set when the Clear to Send (CTS) signal changes state. 

4 Set when the Data Set Ready (DSR) signal changes 
state. 

5 Set when the Data Carrier Detect (DCD) signal changes 
state. 

6 Set when a breaic is detected. 
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7 Set when a parity, framing or overrun error occurs (an 
overrun can be a receive hardware overrun or a receive 
queue overrun). 

8 Set when trailing edge of Ring Indicator is detected. 

9 to 15 Undefined 



Returns 

If the call is made with an Invalid Parameter Packet value, a general 
failure error is reported, valid Information is not returned In the Data 
Packet, and the event word is not cleared. 

Remarks 

If a general failure is not returned, the device driver will return the 
current value of the event word and then clear it. 
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Purpose 

Return Device Control Block (DCB) Information 

Parameter Packet Format 

None. Packet pointer must be NULL. 



Data Packet Format 



Field 


Length 


Write Timeout 


WORD 


Read Timeout 


WORD 


Flagsl 


BYTE 


Flags2 


BYTE 


FlagsS 


BYTE 


Error Replacement Character 


BYTE 


Break Replacement Character 


BYTE 


XON Character 


BYTE 


XOFF Character 


BYTE 



Where 

Write Timeout 

specifies the time period used for write timeout processing. The 
value is in .01 second units ( based on zero, where zero equals .01 
seconds). Refer to Note 8: Write Timeout earlier In this chapter. 

Read Timeout 

specifies the time period used for read timeout processing. The 
value is in .01 second units ( based on zero, where zero equals .01 
seconds). Refer to Note 9: Read Timeout earlier in this chapter. 
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Flagsl 

Bit Meaning 

0-1 DTR Control Mode 



Biti 


BitO 




0 


0 


Disable 


0 


1 


Enable 


1 


0 


Input handshaking 



2 Reserved (returned as zero) 

3 Enable output handshaking using CTS 

4 Enable output handshaking using DSR 

5 Reserved (returned as zero) 

6 Enable input sensitivity using DSR 

7 Reserved (returned as zero) 

Flags2 

Bit Meaning 

0 Enable automatic transmit flow control (XON/XOFF) 

1 Enable automatic receive flow control (XON/XOFF) 

2 Enable error replacement character 

3 Enable null stripping (remove null bytes) 

4 Enable break replacement character 

5 Reserved (returned as zero) 
6-7 RTS Control Mode 



Bit? 


Bite 




0 


0 


Disable 


0 


1 


Enable 


1 


0 


Input handshaking 


1 


1 


Toggling on transmit 
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Flag83 

Bit Meaning 

0 Enable write infinite timeout processing 

1-2 Read timeout processing 
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Bit 2 0ft t 

0 1 Normal read timeout processing 

1 0 Walt for something, read timeout proc- 
essing 

1 1 No wait, read timeout 
processing 

3 Reserved (returned as zero) 

4 Reserved (returned as zero) 

5 Reserved (returned as zero) 

6 Reserved (returned as zero) 

7 Reserved (returned as zero) 

See function 531-1, Set Device Control Block (DCB) for field defi- 
nitions. 

Error Replacemettt Character 

any byte value In the range OOH to FFH. Refer to Note 5: Error 
Replacement Character earlier in this chapter. 

Break Replacement Character 

any byte value in the range OOH to FFH. Refer to Note 7: Break 
Replacement Character earlier In this chapter. 

XON Character 

any byte value in the range OOH to FFH. Refer to Note 2: Auto- 
matic Flow Control earlier In this chapter. 

XOFF Character 

any byte value In the range OOH to FFH. Refer to Note 2: Auto- 
matic Flow Control earlier in this chapter. 

Returns 

If the call is made with an invalid Parameter Packet value, a general 
failure error is reported and valid Information Is not returned in the 
Data Packet. 
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Remarks 

The general Device Control Block (DCB) parameter access functions 
(53H and 73H) are used for: 

• Automatic transmit flow control (start/stop transmit when 
XON/XOFF character received) 

• Automatic receive flow control (transmit XON/XOFF when 
receive buffer fills/empties) 

• Determine XON/XOFF characters 

• DTR control mode (enable/disable/input handshaking) 

• RTS control mode (enable/disable/input handshaking/toggling on 
transmit) 

• Output handshaking using CTS/DSR/DCD (control signal deter- 
mines when to transmit) 

• Input sensitivity using DSR (reception of data controlled by DSR) 

• Error replacement character and processing 

• Break replacement character and processing 

• Null stripping 

• Receive/transmit timeout processing 

if a general failure error is not returned, the device driver will return 
valid information In the Data Packet. 

Note: To maintain upward compatibility, It is the responsibility of the 
application to do a Return Device Control Block (DCB) Information 
BEFORE doing a Set Device Control Block (DCB). The appropriate 
information in the returned control block should be modified by the 
application and then the Set function can be done. 
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Following Is a summary of Category 3 descriptions: 

Function Description 

72H Get pointer draw address 
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Purpose 

Get pointer draw address 

Parameter Packet Format 

None 



Data Packet Format 



Field 


Length 


Return Code 


WORD 


Pointer Draw Routine Entry Point 


DWORD 


(Seiector-.Offset) 




Pointer Draw Routine Data Segment 


WORD 


Selector 





Returns 

Information in data pacl<et defined above. 
Remark 

Tlie call is used by the mouse subsystem to obtain the entry point 
address of the pointer draw routine. The pointer draw routine is con- 
tained within the pointer draw device driver. It is called by the mouse 
device driver to update the pointer image on the screen. The far 
address returned by function code 721-i is passed by the mouse sub- 
system to the mouse device driver through an lOCtI interface (refer- 
ence the mouse control lOCtI commands, category 07H). The mouse 
device driver saves the far address passed and uses it when calling 
the pointer draw routine. 

This function is supported by the pointer draw device driver. 
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Following Is a summary of Category 4 descriptions: 
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Get Interim character flags 


73H 


Get shift state 


74H 


Read character data record(s) 


75H 


Peek character data record 


76H 


Get session manager Hot Key 


77H 


Get keyboard type 


78H 


Get code page ID 


79H 


Translate scan code to ASCII 
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Purpose 




Set Code Page 




Parameter Packet Format 




Field 


Length 


Pointer to Code Page 


DWORD 



Data Packet Format 

None 



Where 

Code Page Format 

has the following format where there are 127 copies of the KeyDef 
rec below (includes 1 for each possible scan code that may be 
returned from the keyboard). Not ail entries are used; unused 
entries are zero. The entries are in scan code order, based on the 
remapped scan codes returned by the l<eyboard controller when it 
is in the DOS execution environment. The DOS execution environ- 
ment translates keyboard scan codes to scan codes based on the 
position of the keys as they are on the standard PC keyboard (plus 
additional keys on the Enhanced Keyboard). The DOS execution 
environment also converts key "break" codes to the equivalent 
scan code with the high order bit turned on (that is, adds 128 to 
the code). 
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XlateTable: 

XHeader : XHeader 

KeyDefl : KeyDef 

KeyDef2 : KeyDef 

KeyDefS : KeyDef 



KeyDefl27 

AccentTbl 
End XlateTable 
XHeader: 

XTablelD 

XTableFlagsl 



ShiftAlt 

AltGrafL 

AltGrafR 

ShiftLock 

DefaultTable 

ShiftToggle 

AccentPass 



KeyDef 
AccentTabl e 



CapsShift 

Reserved 

Reserved 
EndRec XtableFlagsl 
XTableFlagsZ : 

Reserved : 
EndRec XtableFlags2 
KbdType : 
KbdSubType : 
Xtabl eLen : 
EntryCount 



] 



Word [Code Page ID 

Rec[Word Width] 

The following three bits determine which 
shift key or key combination affects CHARS 
of each KeyDef. 

Bit 0 [Use Shift-Alt instead of Ctrl -Alt] 
Bit 1 [Use left Alt key as Alt-Graphics] 
Bit 2 [Use right Alt key as Alt-Graphics] 
Bit 3 [Treat Caps Lock As Shift Lock ] 
Bit 4 [Default table for the Lang.] 
Bit 5 [Toggle or Latch ShiftLock] 

When 1 toggle else latch 
Bit 6 [Pass accent and non-accent key through] 

When 1 pass on accent keys and beep, 

else beep only. 
The following four bits determine which 
shift key or key combination causes CharS 
to be used in each KeyDef. 
Bit 7 [Caps-Shift uses CHARS] 
Bit 8-10 
Bit 11 - 15 

Rec[Word Width] 
Bit 0 - 15 

Word [Keyboard type, see below ] 

Word [Reserved . ] 

Word [Length of Table ] 

Word [Number of KeyDef entries ] 
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EntryWidth : Word 

Country : Word 

TableTypelD : Word 

Reserved : 10 Words 

End XHeader 

KeyDef = Rec 
XlateOp = Rec [word field] 
AccentFlags : 7 Bits 
Key Type : 9 bits 
Charl : Byte 
Char2 : Byte 
Char3 : Byte 
Char4 : Byte 
CharS : Byte 

EndRec KeyDef 

AccentTable = Rec 
AccentEntryl : AccentEntry 
AccentEntry2 : AccentEntry 



[Width of KeyDef entries ] 
[Language ID ] 
[Identifies the table type ] 
[Reserved. ] 

[127 copies of this record.] 
[Translate operation specifier.] 
[See notes 1 and 8, below.] 
[Note 2, below.] 

[Use depends on Key Type, below.] 
[Use depends on Key Type, below.] 
[Use depends on Key Type, below.] 
[Use depends on Key Type, below.] 
[Use depends on Key Type, below.] 

[Table of accent key definitions.] 



AccentEntry7 : AccentEntry 
EndRec AccentTable 



AccentEntry = Rec [Accent entry definition. See notes 1 and 9.] 
NonAccent : 2 Bytes [Char/scan code when not used as accent] 
Ctl Accent : 2 Bytes [Char/scan code when used with CTL. ] 
AltAccent : 2 Bytes [Char/scan code when used with ALT. ] 
Mapl : 2 Bytes [From char to char for translation. ] 
Map2 : 2 Bytes 



Map20 : 2 Bytes 
EndRec AccentEntry 



TableTypelD 

1st byte 2nd byte 

type sub-type 

OOX Reserved 

OS/2 OIX OOX 
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Notes about the Code Page 

1. The AccentFlags field of the KeyDef record has seven flags that 
are individually set if a corresponding entry in the accent table 
applies to this scan code. If the key pressed immediately before 
the current one was an accent key, and the bit for that accent is 
set in the AccentFlags field for the current key, the corresponding 
AccentTable entry is searched for the replacement character 
value to use. If no replacement is found the "not-an-accent" beep 
is sounded and the accent character and current character are 
passed as two separate characters. Also see note 8. 

2. The KeyType field of the KeyDef record currently has the fol- 
lowing values defined. The remaining values up to 1FH are unde- 
fined. In the following table the effect of each type of shift is 
defined. Except where otherwise noted, when no shifts are 
active, Char1 is the translated character. References to undefined 
are clarified In note 3 below. Note that either the ALT, ALTC/S/G 
or both may be present on a keyboard based on the AltGrafL and 
AltGrafR bits in the XTableFlagsl flagword in the table header. 

• 01 H) AlphaKey - Alphabetical character key: 

SHIFT - Uses Char2 (If CAPSLOCK, uses Charl). 

CAPSLOCK- Uses Char2 (If SHIFT, uses Charl). 

CTL - Set standard "control" code for this key's 

Charl value (see note 4 below). 
ALT - Standard "extended" code (see note 7). 

ALTC/S/G - Uses Char 3 if it is not zero 



• 02H) SpecKey - Special non-alphabetical character key, no 
CAPSLOCK or Alt: 

SHIFT - Uses Char2. 

CAPSLOCK- No effect, only depends on SHIFT or CTL. 
CTL - See note 4 below. 
ALT - Marked undefined. 

ALTC/S/G - Uses Char 3 if it is not zero 



• 03H) SpecKeyC - Special non-alpha character key with 
CAPSLOCK See note 15. 
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SHIFT - Uses Char2 (If CAPSLOCK, uses Charl), 
CAPSLOCK- Uses Char2 (If SHIFT, uses Charl). 
CTL - See note 4 below. 
ALT - Use Char4 if not zero. 

ALTC/S/G - Uses Char 3 if it is not zero 



• 04H) SpecKeyA - Special non-alpha character key, with ALT 
(no CAPSLOCK): 

SHIFT - Uses Char2 

CAPSLOCK- No effect, only depends on SHIFT. CTL or ALT. 
CTL - See note 5 and note 9 below. 
ALT - See note 7 below. 

ALTC/S/G - Uses Char 3 if it is not zero 



• 05H SpecKeyCA - Special non-alpha character key, with 
CAPSLOCK & Alt: 

SHIFT - Uses Char2 (If CAPSLOCK. uses Charl). 

CAPSLOCK- Uses Char2 (If SHIFT, uses Charl). 

CTL - See note 4 below. 

ALT - See note 7 below. 

ALTC/S/G - Uses Char 3 if it is not zero 



• 06H) FuncKey - Function keys (Charl = "n" in "Fn", Char2 
ignored, sets "extended" codes 58+ Charl if no shift or if F11 
or F12, uses 139 and 140). 

SHIFT - Sets "extended" codes 83+Charl; 

FU and F12 use 141 and 142 respectively 
CAPSLOCK- No effect on function keys. 
CTL - Sets "extended" codes 93+Charl; 

FU and F12 use 143 and 144 respectively 
ALT - Sets "extended" codes 103+Charl; 

FU and F12 use 145 and 146 respectively. 

ALTC/S/6 - Uses Char 3 if it is not zero 
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07H) PadKey - Keypad keys (see note 5 for definition of 
Ciiar1 , and note that non-shifted use of these l<eys is fixed to 
the "extended" codes): 

SHIFT - Uses Char2 (Unless NUMLOCK, then see note 5). 
CAPSLOCK- No effect on pad keys (NUMLOCK does, note 5). 
CTL - Sets "extended" codes (see note 5). 
ALT - Used to "build" a character (see note 5). 

ALTC/S/6 - Uses Char 3 if it is not zero 

081-1) SpecCtlKey - "Action" Iceys that do special things with 
Ctrl down: 

SHIFT - No effect on these keys. 
CAPSLOCK- No effect on these keys. 
CTL - Uses Char2. 
ALT - Marked undefined. 

ALTC/S/G - Uses Char 3 if it is not zero 



09H) PrtSc - Print Screen key (sets Char1 normally): 

SHIFT - Signal the Print Screen function. 

CAPSLOCK- No effect on this key. 

CTL - Sets extended code and signals 

the Print Echo function. 
ALT - Marked undefined. 

ALTC/S/G - Uses Char 3 if it is not zero 

OAH) SysReq - System Request key; treated like a shift key. 
(See note 6 below). 

OBH) AccentKey - Keys that affect the "next" key pressed 
(also known as dead keys). Char1 is an index into the 
AccentTbl field of the XIateTable, selecting the AccentEntry 
that corresponds to this key. Char2 and CharS do the same 
for the shifted Accent character. See note 15. 
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SHIFT - Use Char2 to index to applicable Accent Entry. 

CAPSLOCK- No effect on this key. 

CTL - Use Ctl Accent character from AccentEntry 

(see note 8). 
ALT - Use AltAccent character from AccentEntry 

(see notes). 

ALTC/S/G - Use Char3 to index to applicable AccentEntry. 



Note: Key types OCH through 13H set Char1 & Char2 to mask 
values as defined in note 6 below. 

• OCH) ShiftKeys - SHIFT or Ctrl key, sets/clears flags. Char1 
holds the bits in the lower byte of the shift status word to set 
when the key is down and clear when the key is released. 
Char2 does the sanne thing for the upper byte of the shift 
status word, unless the "secondary" key prefix (hex EO) is 
seen immediately prior to this key, in which case Char3 is 
used in place of Char2. 

• ODH) ToggleKey - General toggle key (like Caps Lock). 
Char1 holds the bits in the lower byte of the shift status word 
to toggle on the first make of the key after it is pressed. 
Char2 holds the bits in the upper byte of the shift status word 
to set when the key is down and clear when the key is 
released unless the "secondary" key prefix (hex EO) is seen 
immediately prior to this key. In which case CharS is used in 
place of Char2. 

• OEH) ALTKey - ALT key. Treated just like ShiftKeys above, but 
has its own key type because when seen, the accumulator 
used for ALT-Padkey entry is zeroed to prepare such entry. 
See note 5 for more information about ALT-PadKey entry. 
Sometimes this key is treated as "ALTC/S/G" key if one of the 
AltGraf bits is on in XTableFlagsl. 

• OFH) NumLock - NUMLOCK key. Behaves like ToggleKey 
normally, but the KBDDD will set a pause screen indication 
when this key is seen along with the Ctrl key depressed. The 
pause is cleared on the following keystroke, If that stroke Is a 
character generating key. 
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10H) Caps Lock - The Caps Lock key. This key is treated 
exactly like a type ODH toggle key. It has a separate entry 
here so that if it can be processed like a shift lock key when 
that flag is set in the XTableFlagsl word in the header. When 
treated as a ShiftLock, the Caps Lock flag in the shift status 
word is set ON on any make of this key, and only cleared 
when the left or right shift key is depressed. Char2 and CharS 
are processed the same as ToggleKey. 

11H) ScrollLock - SCROLL LOCK key. Behaves like 
ToggleKey normally, but has a separate entry here so that 
when used with "Ctrl-" it can be recognized as "Ctrl-Break". 

12H) XShiftKey - Extended Shift Key (for Country Support). 
See note 9 for more information. 

13H) XToggleKey - Extended Toggle Key (for Country 
Support). See note 9 for more information. 

14H) SpecKeyCS - Special key 1 for foreign keyboard proc- 
essing. See note 15 for more information. 



SHIFT - Use Char2 

CAPSLOCK - Use Char4 

CTL - See note 4 below. 

ALT - No effect on this key 

ALTC/S/G - Use Char3 



CAPS+SHFT - Use CharS 

15H) SpecKeyAS - Special key 2 for foreign keyboard proc- 
essing. See note 15 for more information. 



SHIFT - Use Char2 

CAPSLOCK - No effect on this key 

CTL - See note 4 below. 

ALT - Use Char4. See note 14 below 

ALTC/S/G - Use Char3. See note 14 below 



16-19H) Reserved 
20-1FFH) Reserved 
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3. Undefined Character Code: Any key combination that doesn't fall 
into any of the defined categories (e.g., the Ctrl l<ey pressed 
along with a key that has no defined control mapping) will be 
mapped to the value 0 and the keytype will be set in the 
KeyPacket record indicating undefined translation. The 
KeyPacket record passed to the monitors (if any are installed) 
will contain the original scan code in the ScanCode field and the 
0 in the Character field for this key. Note that no chardata recs 
with an undefined character code will be placed in the keyboard 
input buffer. 

4. Ctrl Key Notes: There are six possible situations for when a key is 
pressed along with only the Ctrl shift key. They are: 

a. The key pressed is an AlphaKey character. In this case the 
Ctrl plus Char1 combination defines one of the standard 
defined control codes. They are (all numbers are decimal): 



Ctrl- 


Mapping 


Code Name 


Ctrl- 


Mapping 


Code Name 


a 


1 


SOH 


n 


14 


SO 


b 


2 


STX 


0 


15 


SI 


c 


3 


ETX 


P 


16 


OLE 


d 


4 


EOT 


q 


17 


DCl 


e 


5 


ENQ 


r 


18 


DC2 


f 


6 


ACK 


s 


19 


DC3 


9 


7 


BEL 


t 


20 


DC4 


h 


8 


BS 


u 


21 


NAK 


1 


9 


HT 


V 


22 


SYN 


J 


10 


LF 


w 


23 


ETB 


k 


11 


VT 


X 


24 


CAN 


1 


12 


FF 


y 


25 


EM 


m 


13 


CR 


z 


26 


SUB 



Note that any key defined as AlphaKey will use the Char1 
code value minus 96 (ASCII code for "a") plus 1 to set the 
mapping shown above. So any scan code defined as 
AlphaKey must assign to Char1 one of the allowed lower 
case letters. 

b. The key pressed is a non-alpha character (like "["), but is not 
an "action" key (like Enter, Backspace, or an arrow key). 
This is a SpecKey[C][A] In the list of key types above, in this 
case (with one exception) the mapping is based on the scan 
code of the key. Though the key may be re-labeled, the 
Ctrl + Char combination is always mapped based on the scan 
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code of the key using the following table (all numbers are 
decimal): 

Scan US Kbd Mapped Name of 
Code Legend Value New Code 



3 
7 

* 12 
26 
27 
43 



] } 
\ I 



2 @ 
6 



[ { 



0 

30 

31 

27 

29 

28 



Null 

RS 

US 

Esc 

GS 

FS 



(see note below) 



Note: The mapping for the hyphen character ("-") is the one 
exception. The scan code for it is ignored, only the ASCII 
code for hyphen (decimal 45) is looked for (in Char1) when 
mapping the Ctrl + "-" combination. This is because there 
may be more than one occurrence of the "-" key on the key- 
board. 

c. The key pressed is an "action" key like Enter, backspace, or 
an arrow key. These keys generate special values when 
used In conjunction with the Ctrl key. Those actions are 
defined in other notes where they apply. 

d. The key pressed is a function key (F1 - F12). 

e. The key pressed is an accent key. See note 8 for details. 

f. The key is not defined in conjunction with Ctrl. In that case, 
the key will treated as undefined, as described in note 3. 

5. Pad Key Notes: The pad keys have several uses depending on 
various shift states. Some of them are based on their position on 
the keyboard. Because keyboard layouts change, here are the 
hard coded assumed positions of the keypad keys, with the 
"offset" value that must be coded into Char1 of the table. Any 
remapping must use the Char1 values defined below for the keys 
that correspond to the pad keys given by the Legend or Char2 
values shown: 
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us Kbd 


Scan 


Charl 




Char2 


Legend 


Code 


REQUIRED 


US Kbd 


Home 7 


71 


Binary 0 


ASCII 7 


Up 8 


72 


II 


1 


" 8 


PgUp 9 


73 


II 


2 


II 9 


- 


74 


II 


3 




Left 4 


75 


II 


4 


" 4 


5 


76 


II 


5 


" 5 


Right 6 


77 


II 


6 


" 6 


+ 


78 


II 


7 


" + 


End 1 


79 


II 


8 


" 1 


Down 2 


80 


11 


9 


II 2 


PgDn 3 


81 


II 


10 


" 3 


Ins 0 


82 


II 


11 


" 0 


Del . 


83 


II 


12 





Note that when NumLock is OFF, or If Shift Is active & NunnLocl< 
ON, the code returned is the "extended" code. The code returned 
corresponds to the Legends above (Home, PgUp, etc). When 
NumLocl< is ON, or if SHIFT Is active & NumLoci< is OFF, the code 
returned Is Char2. Note that the " + " and "-" keys will return 
Char2 under ALL shift combinations except Ait (see below). 

When the Alt key Is used with the PadKeys, the absolute value of 
the pressed key (looked up using the required Charl value) is 
added to the accumulated value of any of the previous numeric 
keys pressed without releasing the Alt key. Before adding the 
new number to the accumulated value, that accumulation is multi- 
plied by ten, with overflow beyond 255 Ignored. When Alt is 
released, the accumulation becomes a Character code, and Is 
passed along with a scan code of zero. Note that if any key other 
than the 10 numeric keys is hit, the accumulated value is reset to 
zero. 

When AltGraphlcs Is used with the PadKeys the CharS value Is 
returned If it Is non-zero and If an AltGraf bit is set in 
XTabieFiagsl; otherwise It Is treated the same as the Alt key. 
6. State Key Notes: Each state key entry has Charl , Char2, and 
CharS defined as follows: 

Charl is a mask to set the appropriate bit in the low byte of the 
keyboard Shift Flags when the state key is pressed. When the 
state key Is a toggle key, the set bit will be toggled each addl- 
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tional time the key is pressed. When the state key is not a toggle 
key, the set bit will be cleared when the key is released. 

Char2 is a nnask to set the appropriate bit in the high byte of the 
Keyboard Shift Flags when the key is pressed. 

CharS is used in place of Char2 when the secondary key prefix is 
seen immediately prior to this key. 

The masks are (numbers are in hex): 



Key 


Charl 


Char2 


Char3 


Right Shift 


01 


00 


00 


Left Shift 


02 


00 


00 


Ctrl Shift 


04 


01 


04 


Alt Shift 


08 


02 


08 


Scroll Locic 


10 


10 


10 


Num Lock 


20 


20 


20 


Caps Lock 


40 


40 


40 


SysReq 


00 


80 


80 



Note that the INS key is not treated as a state key, but as a Pad 
key. Also note that SysReq is included here as it is treated as a 
shift key. 

7. Alt Character Notes: Most of the keys defined in a category that 
allows the Alt key (AlphaKey, SpecKeyA, SpecKeyCA) return a 
value called an Extended Character. This value is a character 
code of OOH or EOH with a second byte (using the ScanCode field 
of the CharData record) defining the extended code. In most 
cases this value is the scan code of the key. Since the legend on 
these keys may be remapped on a foreign language keyboard, 
the Alt based extended code is hard to define in a general sense. 
The following rules are used: 

• AlphaKey: The extended code is derived from Charl (the 
"lower case" character) as it was originally mapped on the 
PC keyboard. The original scan code value itself is the 
extended code that a character will return. These keys can 
be moved and will still return their original Alt extended 
codes. 

• SpecKeyA and SpecKeyCA: This category is used for all keys 
that are not an alphabetical character or an "action" code 
(like Enter or Backspace, the only exception being the tab key 
which IS treated as a character). On foreign keyboards these 
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keys may be moved around and/or have new values assigned 
to them (such as special punctuation symbols). So the Alt 
mappings must be based on the real scan code. The effect of 

this is that l<eys defined by the SpecKey classification will 

only have an Alt mapping if it is in one of the positions 
defined below. In that case the Alt extended code is as 
shown in the table. 



Scan 


US Kbd 


ALT 


Scan 


US Kbd 


ALT 


Code 


Legend 


Value 


Code 


Legend 


Value 


2 


1 ! 


120 


8 


7 & 


126 


3 


2 @ 


121 


9 


8 * 


127 


4 


3 # 


122 


10 


9 { 


128 


5 


4 $ 


123 


11 


0 ) 


129 


6 


5 % 


124 


12 




130 


7 


6 " 


125 


13 


= + 


131 



• FuncKey: Defined in note 2. 

When AltGraphics is used the CharS value is returned if it is 
non-zero and if an AltGraf bit is set in XTableFlagsl ; otherwise it 
is treated the same as the Alt key. 
8. Accent Key Notes: When an accent key is pressed along with Ctrl 
or Alt it is treated as a regular key. The character it is translated 
to is the one in the CtlAccent or AltAccent field of the AccentEntry 
pointed to by the CharS value of the KeyDef. If the key being 
defined will have no defined value with Ctrl or Alt, it should have 
zeroes in the field of the undefined combination. 

When an accent key is pressed by itself (or with Right or Left Shift 
or AltGraphics) it will not be translated immediately. The Char1 
(or Char2 when Left or Right Shift is used or when the 
AltGraphics is used) index in the KeyDef record will be used with 
the next key received to check if the next key has an accent 
mapping. If that next key has no mapping for this accent (i.e., if it 
has no bit set in its AccentFlags for this accent, or If that next key 
is not found in this accent's AccentEntry) then the character value 
in the NonAccent field of the AccentEntry is used as the character 
to display, followed by the translation of that next key (i.e., both 
characters are passed on) after the not-an-accent beep is 
sounded. 
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Note that if a key doesn't change when a left or right shift key is 
held down it should use the same value for Charl and Char2 so 
that the accent will apply in both the shifted and non-shifted 
cases. If the accent value is undefined when used with a shift key 
or AltGraphics the value in Char2 or Char3 should be zero. 

Any accent key that doesn't have an Alt or Ctrl mapping should 
put zeros In the AltAccent and CtlAccent fields of its AccentEntry. 
If the value in the table is between 1 and 7 then the key is consid- 
ered an accent key and further accent key processing is indi- 
cated. Reference note 1 for further information. 
9. Extended State Key Notes: For special Country support, the Key- 
board Device Driver maintains another byte of shift status. Key 
types 12H and 13H are provided for manipulation of that byte. 
The other fields of the KeyDef are: 

• Charl: A mask where the bits that are on are those bits that 
define the field being used for the Char2 value. Only the bits 
in the NLS shift status byte that correspond to the bits in this 
byte will be altered by the Char2 value. 

• Char2: For KeyType 12H (Extended Shift), the value to OR into 
the byte when the make code is seen and who's inverted 
value is ANDed when the break code is seen. For KeyType 
13H (Extended Toggle), the value XORed into the byte on 
each make code seen (break code Ignored). 

• CharS: Use in place of the Char2 when the "secondary" key 
prefix (hex EO) is seen immediately prior to this key. 

Examples of usage are: Charl /2 can define single shift status 
bits to set/clear/toggle. Char2 can be a set of coded bits 
(delineated by Charl) that will be set to a numeric value 
when the key is hit and cleared to zero when released (or on 
the next hit If toggle). The whole byte can be set to Char2 
when Charl has all bits on. 
10. Space Key Note: The key treated as the space character should 
have a flag set In its AccentFlags field for each possible accent 
(i.e., for each defined AccentEntry in the AccentTable). And each 
AccentEntry should have the SPACE character defined as one of 
its accented characters, with the translation being to the same 
value as the accent character itself. The reason for this is that, by 
definition, an Accent Key followed by the space character maps 
to the accent character alone. If the table is not set up as just 
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described, a not-an-accent beep will be sounded whenever the 
accent l<ey followed by a space is pressed. 

Note that the space key is defined as a SpecKeyA (type 4) 
because its use in conjunction with the Alt key is allowed. In that 
case it will still return the ASCII space character. It will also 
return the ASCII space character when used with the Ctrl key. 

This works correctly except in the case of the diaresis accent 
(double-dot) in code page 437. Here, the space is treated as an 
invalid character and the beep result occurs, with the diaresis 
represented by double quote. Characters are displayed 
depending upon the language in effect when the invalid diaresis 
is encountered. For some languages the character substituted is 
the double-quote; for others, the character used is the F9h char- 
acter. 

11. KbdType will identify the hardware specific keyboard this table is 
for. The values and allowable types are the same as specified in 
the Get Keyboard Type, lOCtI 77H. 

12. The DefaultTable flag in XtableFlagsl is used by the KEYB utility 
in loading code pages when changing from one language to 
another. It identifies the default code page to KEYB should KEYB 
not find one or both CODEPAGE= defined code pages. 

13. The language IDs used are as follows: 



Keyboard 




Layout 




Code 


Country 


US 


UNITED STATES 


UK 


UNITED KINGDOM 


GR 


GERMANY 


FR 


FRANCE 


IT 


ITALY 


SP 


SPAIN 


DK 


DENMARK 


NL 


NETHERLANDS 


SU 


FINLAND 


NO 


NORWAY 


PC 


PORTUGAL 


SV 


SWEDEN 


SF 


SWISS-FRENCH 


SG 


SWISS-GERMAN 
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CF 
BE 
LA 



CANADIAN-FRENCH 
BELGIUM 

LATIN-AMERICAN SPANISH 



14. Keytype 15: When ALT or ALT + SHFT key is pressed both the 
XlatedChar and XIatedScan In the CharData record will have the 
same value. 

15. If the Charx value is in the range of 1 - 7 then Charx identifies an 
accent key; otherwise Charx Is treated as a valid ASCII character. 
This does not apply to CTL-Charx sequences. 

16. If either the ALTGRF, ALT SHIFT, or ALT CTL are pressed and 
CharS is zero, the ALT key will be used to translate to a valid 
result. 

17. Size: The code page described here is of the following 

dimensions: 

XI ate Header = 40 

127 KeyDefs @ 7 Bytes = 889 

7 AccentEntri es @ 46 Bytes = 322 



Returns 

None 

Remarks 

This request changes the device driver resident code page for the 
system. This lOCtI updates the ZERO entry of the code page control 
block. 



1251 Bytes 
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Purpose 

Set Input Mode 




Parameter Packet Format 




Field 


Length 


Mode 


BYTE 


Data Packet Format 

None 




Where 




Mode 

is a 1-byte field containing: 




Sit Meaning 
Ixxxxxxl Shift Report 
OxxxxxxO ASCII mode 
Ixxxxxxx BINARY mode 




Returns 

None 





Remarks 

This request is used to pass the current input mode to the l<eyboard 
device driver. The Iceyboard device driver will maintain the mode 
separately for each session. The caller can Interrogate the mode 
using function code 71 H. The mode is also returned on every READ 
CHARACTER DATA RECORD(S) call, function code 74H, and PEEK 
CHARACTER DATA RECORD call, function code 75H. The default 
input mode is ASCII. The device driver uses mode when processing 
CTL functions and reporting the shift state when shift report is set on. 
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PurDose 

Set Interim Character Flags 




Parameter Packet Format 




Field 


Length 


Flag 


BYTE 



Data Packet Format 

None 



Where 

Flag 

is a 17-byte field containing flag bits. A bit set = to 1 indicates the 
state listed below: 



Bit 


Meaning 


7 


Interim console flag on 


6 


Reserved = 0 


5 


Program requested on-the-spot conversion 


4 


Reserved = 0 


3 


Reserved = 0 


2 


Reserved = 0 


1 


Reserved = 0 


0 


Reserved = 0 



Returns 

None 

Remarks 

This request is used to set the interim character flags maintained by 
the {keyboard device driver. The keyboard device driver will maintain 
the flags separately for each session. The keyboard device driver 
passes the interim character flags with each character data record to 
keyboard monitors. 



6-89 



Category 4 - 
Function 53H 




Purpose 

Set Shift State 




Parameter Packet Format 




Field 


Length 


Shift State 


WORD 


NLS 


BYTE 



Data Packet Format 

None 



Where 

Shm state 

is a word field containing shift states. 

Word High Byte 

Bit Meaning 

15 SysReq Key down 

14 Caps Locl< Key down 

13 NumLocIc Key down 

12 Scroll Lock Key down 

11 Right Alt Key Down 

10 Right Ctrl Key Down 

9 Left Alt Key Down 

8 Left Ctrl Key Down 
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Category 4 - 
Function 53H 



Word Low Byte 



tilt 


NlBaning 


7 


Insert On 


6 


Caps Lock On 


5 


N urn Lock On 


4 


Scroll Lock On 


3 


Either Alt Key Down 


2 


Either Ctrl Key Down 


1 


Left Shift Key Down 


0 


Right Shift Key Down 


NLS 





is a byte field containing NLS shift status. 

Returns 

None 

Remarks 

This request is used to set the current shift state for the keyboard. 
The keyboard device driver maintains the shift state separately for 
each logical keyboard. Note that this call will override the shift state 
set by previous shift keystrokes. Also the shift state set by this func- 
tion code will be overridden by any subsequent shift keystrokes. The 
shift state is inserted into the character data record that is built for 
each incoming keystroke. 
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Category 4 ~ 
Function 54H 



Purpose 




Set Typematic Rate and Delay 




Parameter Packet Format 




Field 


Length 


Delay 


WORD 


Rate 


WORD 



Data Packet Format 

None 

Where 
Delay 

specifies the typematic delay in nriiiilseconds. A value greater 
than the maximum value defaults to the maximum value. 

Rate 

specifies the typematic rate In characters per second. A value 
greater than the maximum value defaults to the maximum value. 

Returns 

None 

Remarks 

This request is used to set the Iteyboard typematic rate and delay to 
the values specified in the request. 
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Category 4 >^ 
Function 5iH 



Purpose 




Notify of Change of Foreground Session 




Parameter Packet Format 




Field 


Length 


Session Number 


WORD 


Terminate Fiag 


WORD 



Data Packet Format 

None 

Where 

Session Number 

is a one word field containing the new foreground session. The 
session number must fail within the range 0 through 15. 

Terminate Flag 

Is a one word field indicating whether the session is being termi- 
nated. A -1 value indicates termination otherwise non-termination 
is indicated. 

Returns 

None 

Remarks 

This request is used to tell the keyboard device driver a new fore- 
ground session has been made active. The keyboard device driver 
will set the shift state of the keyboard to the state that was current 
when the new session was last active. The keyboard device driver 
will begin using the keyboard input buffer (KIB) and keystroke 
monitor chain associated with the new session. This command is 
restricted and may only be used by the first process that makes the 
call. 
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Category 4 - 
Function 56H 



Purpose 

Set Session Manager Hot Key 



Parameter Packet Format 



Field 


Length 


State 


WORD 


Make Code 


BYTE 


Break Code 


BYTE 


Hot Key ID 


WORD 


Data Packet Format 

None 




Where 




State 





High Byte 

Bit Meaning 

15 SysReq 

14 Caps Lock Key down 

13 N urn Lock Key down 

12 Scrol I Lock Key down 

1 1 Right Alt Key Down 

10 Right Ctrl Key Down 

9 Left Alt Key Down 

8 Left Ctrl Key Down 
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Category 4 - 
Function 56H 



Low Byte 

Bit Meaning 

7 Reserved = 0 

6 Reserved = 0 

5 Reserved = 0 

4 Reserved = 0 

3 Reserved = 0 

2 Reserved = 0 

1 Left Shift Key Down 

0 Right Shift Key Down 

Make Code 

is the scan code of the hot Icey make 

Breal( Code 

is the scan code of the hot Icey breal< 

Hot Key ID 

is the hot Icey ID (Value is set by the caller). 

Returns 

None 

Remarks 

This request is used by the session manager to set a list of Iceyboard 
hot keys the keyboard device driver will begin looking for. The new 
hot key is global, that is, it applies to all sessions. Up to 16 hot keys 
can be defined by the session manager for handling by the keyboard 
device driver. This iOCtI call will only be successful if done by the 
process which initially Invoked lOCtI 55H (Set Foreground Session). 
The combination of the shift flags in the first word and the scan codes 
in the second allow the session manager to set hot key combinations 
such as Alt + Esc. The hot key is triggered on detection of the scan 
code for the hot key break. 
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Category 4 - 
Function 56H 



Note: If a DOS execution environment application has claimed hard- 
ware interrupt 9 or Interrupt 50, the hot key will be triggered on 
detection of the break scan code for the required shift key. 

A hot key can be redefined by calling this function with the same hot 
key ID. 
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Category 4 - 
Function 57H 



Purpose 




Set KCB 




Parameter Packet Format 




Field 


Length 


KCB Handle 


WORD 



Data Packet Format 

None 

Where 

KCB Handle 

is the handle identifying the logical keyboard's KCB. 

Returns 

None 

Remarks 

This request binds the specified logical keyboard (KCB) to the phys- 
ical keyboard for this session. 
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Category 4 - 
Function 58H 



Purpose 

Set Code Page ID 




rarameier KaCKei rornfiai 




Field 


Length 


Code Page Pointer 


DWORD 


Code Page ID 


WORD 


Set to Zero 


WORD 



Data Packet Format 

None 

Where 

Code Page Pointer 

is the selector:offset pointing to the code page. 

Code Page 10 

is one word containing the current code page ID. 

Returns 

None 

Remarks 

Sets the code page used by the current KCB to the code page identi- 
fied by the input parameter. This lOCtI is callable from the DOS exe- 
cution environment. 
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Category 4 - 
Function 5CH 



Purpose 

Set NLS and Custom Code Page 



Parameter Packet Format 



Field 


Length 


Code Page Pointer 


DWORD 


Code Page Number 


WORD 


Code Page to Load 


WORD 


Hot Key ID 


WORD 


Data Packet Format 

None 



Where 

Code Page Pointer 

is tlie selector.offset pointing to the code page. 

Code Page Number 

is one word identifying tlie code page number. 

Code Page to Load 

is one word identifying the number of the code page to load, 1 or 
2. A -1 indicates a custom code page for which the segment con- 
taining the custom code page will be locked. This option is not 
valid for the DOS execution environment. 

Hot Key ID 

is the hot key ID (Value is set by the caller). 

Returns 

None 
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Category 4 - 
Function 5CH 



Remarks 

This request is used to install one of two possible code pages into 
the device driver. This lOCtI will update the number one or two entry 
of the code page control block; entry zero Is the device driver resi- 
dent code page. Note that this lOCtI Is similar to lOCtI 50H, Set Code 
Page, except that different entries In the code page control blocl< are 
updated. This lOCtI is callable from the DOS execution environment. 
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Category 4 - 
Function 5DH 



Purpose 

Create Keyboard creates a new logical keyboard. 



Parameter Packet Format 


Field 


Length 


KCB ID 


WORD 


Data Packet Format 




None 





Where 

KCB ID 

is one word containing a unique value used to identify the new 
logical keyboard. A zero indicates the default keyboard. 

Returns 

None 

Remarks 

None 
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Category 4 - 
Function 5EH 



Purpose 

Destroy Keyboard destroys an existing logicai keyboard. 



Parameter Packet Format 


Field 


Length 


KCB ID 


WORD 


Data Packet Format 




None 





Where 

KCB ID 

is one word containing a unique value used to identify the new 
iogical iceyboard. A zero indicates the default Iceyboard. 

Returns 

None 

Remarks 

None 
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Category 4 - 
Function 71 H 



Purpose 

Get Input Mode 

Parameter Packet Format 

None 



Data Packet Format 



Field 


Length 


Mode 


BYTE 


Where 




Mode 

is a 1-byte field containing one of the following values: 


Bit 

Ixxxxxxl 
OxxxxxxO 
Ixxxxxxx 


Meaning 

Shift Report 
ASCII mode 
BINARY mode 


Returns 

None 





Remarks 

This request is used to obtain the input mode of the session of the 
currently active process. The input mode can be set with function 
code 51 H. The input mode is meaningful for Ctrl-C, Ctrl-P, Ctrl-S, 
Ctrl-Break, Ctrl-Scroll Lock, and Ctrl-PrtSc processing only. 
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Category 4 - 
Functloii 72H 




Purpose 

Get Interim Character Flags 




Parameter Packet Format 

None 




Data Packet Format 




Field 


Length 


Flags 


BYTE 



Where 

Flags 

is a 1-byte field containing flag bits. A bit set = to 1 indicates the 
state listed below: 



Bit 


Meaning 


7 


Interim console flag on 


6 


Reserved = 0 


5 


Program requested on-the-spot conversion 


4 


Reserved = 0 


3 


Reserved = 0 


2 


Reserved = 0 


1 


Reserved = 0 


0 


Reserved = 0 



Returns 

None 

Remarks 

This request is used to obtain the interim character flags maintained 
by the [keyboard device driver. 
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Category 4 - 
Function 73H 



Purpose 

Get Shift State 

Parameter Packet Format 

None 

Data Packet Format 

None 

Returns 

None 

Remarks 

This request is used to obtain the shift state of the session of the cur- 
rently active process. The shift state is set by incoming l<ey strolces 
and by function code 53H calls. 

Refer to function 53H, Set Shift State for the data structure. 
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Category 4 ~ 




Function 74H 




Purpose 




Read Character Data Record(s) 




Parameter Packet Format 




Field 


Length 


Transfer Count 


WORD 



Data Packet Format 

See "KbdCharIn - Read Character, Scan Code" on page 3-2 for 
the CharData data structure. 

Where 

Transfer Count 

is a one word field containing the record transfer count. The sign 
bit of this word is set to request one of the following actions: 

0 Wait for the requested number of key strokes to become 
available. The device driver will block the requestor until all 
requested character data records are available and have 
been transferred to the caller. 

1 Do not wait for the requested number of key strokes to 
become available. In this case, all characters currently 
available will be transferred, up to the requested transfer 
count. 

Returns 

None 
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Category 4 - 
Function 74H 



Remarks 

This request is used to obtain one or more character data records 
from the keyboard input buffer (KIB) for the session of the currently 
active process. Note that if shift report is on then the CharData 
record may not contain a character but a shift state change in the 
shift status field. 



6-107 



Category 4 - 



Function 75H 




Purpose 

Peek Character Data Record 




rarameter racKet rormai 




Field 


Length 


Status 


WORD 


Data Packet Format 



See "KbdCharIn - Read Character, Scan Code" on page 3-2 for 
the CharData data structure. 

Where 

status 

is a one word field which contains either 0 to indicate no key 
strol<e is available or 1 to indicate that a character data record is 
being returned. The sign bit is set to either 0 if the current input 
mode is ASCII or 1 if the input mode is BINARY. 

Returns 

None 

Remarks 

This request is used to obtain one character data record from the 
head of the Iceyboard input buffer (KIB) of the session for the currently 
active process. The character data record is not removed from the 
KIB. Note that if shift report is on then the CharData record may not 
contain a character but a shift state change in the shift status field. 
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Category 4 - 
Function 76H 



Purpose 

Get Session Manager Hot Key 



Parameter Packet Format 



Field 


Length 


Type 


WORD 


Data Packet Format 




None 




Where 




Type 





is a one word subtype indicating the type of information to return: 

0 Return the maximum number of hot keys the l<eyboard device 
driver can support. 

1 Return the number of hot l<eys currently defined in the system 
and return the key information for each. 

Returned Data Buffer 

If parameter list on entry was 1, one or more hot key data struc- 
tures as described under lOCtI function code 56H (Set Session 
Manager Hot Key). 

Returns 

None 

Remarks 

This request is used to obtain the scan code the {keyboard device 
driver is using as the session manager hot key. 
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Category 4 - 
Function 76H 



This function sliould first be called with parameter list subtype = 0 to 
determine the maximum number of hot keys the device driver can 
support. The value returned should be used to determine the 
required size of the data buffer on a subsequent call to return the hot 
key data structures (parameter list subtype = 1). 
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Category 4 - 
Function 77H 



Purpose 

Get Keyboard Type 

Parameter Packet Format 

None 



Data Packet Format 



Field 


Length 


Keyboard Type 


WORD 


Reserved = 0 


DWORD 


Where 




Keyboard Type 

is a 1-word field containing: 




Highi Byte: Reserved = 0 




Low Byte: 




Value Meaning 

OOH Personal Computer AT keyboard 
01 H Enhanced Keyboard 
02H to FFH Reserved = 0 



Returns 

None 



Remarks 

This request returns the keyboard type. 
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Category 4 ~ 




Function 78H 




Purpose 

Get Code Page ID 




Parameter Packet Format 




Field 


Length 


Code Page ID 


WORD 



Data Packet Format 

None 



Where 
Code Page ID 

Is one word containing the current code page ID. A 0 Indicates 
that PC US 437 is being used; One word reserved and set to Q. 

Returns 

None 

Remarks 

This request returns the code page In use by the current KCB. A -1 Is 
returned if a custom code page Is Installed. This lOCtI Is callable 
from the DOS execution environment. 
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Category 4 - 
Function79H 



Purpose 

Translate Scan Code to ASCII 



Parameter Packet Format 



Field 


Lengtli 


Code Page ID 


WORD 


Data Packet Format 


Field 


Lengtli 


CharData Record 


10 BYTES 


KbdDDFIags 


WORD 


XIate Flags 


WORD 


XIate Statel 


WORD 


XIate State2 


WORD 



Where 

Code Page ID 

is one word containing the current code page ID. 

CharData Record 

See "KbdCharIn - Read Character, Scan Code" on page 3-2 
(10 bytes). 

KbdDDFIags 

as defined in the Device Monitor packets in OS/2 Technical Refer- 
ence, Volume 1 Chapter 2 
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Category 4 - 
Function 79H 



X/ato Flags 



High Byte 



Value 

8-15 



Meaning 
Reserved 



0 



Low Byte 



Value 
1-7 

0 



Meaning 
Reserved = 0 
Translation complete 



Xiate Statel and XIate State2 

identifies the state of translation across successive calls. Initially 
these words should be 0. They should be reset to 0 when the 
caller wants a new start to translation. Note that it may take 
several calls to this lOCtI to complete a character so these fields 
should not be touched unless a fresh start to translation is 
desired. These fields are set to 0 at the completion of translation. 

Returns 

None 

Remarks 

This request translates a scan code in a CharData record to an ASCII 
character. Optionally a code page may be specified to use for trans- 
lation otherwise the code page of the active KCB will be used. 
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Category 5 Printer Control lOCtI Commands 



Following is a summary of Category 5 descriptions: 



Function 


Description 


42H 


Set frame control (CPL, LPI) 


44H 


Set infinite retry 


45H 


Reserved 


46H 


Initialize printer 


48H 


Activate font 


62H 


Get frame control 


64H 


Get infinite retry 


66H 


Get printer status 


69H 


Query active font 


6AH 


Verify font 
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Function 42H 



Purpose 

Set Frame Control 

Parameter Packet Format 



Field 


Length 


Command Information 


BYTE 


Data Packet Format 


Field 


Length 


Characters per Line 


BYTE 


Lines per Inch 


BYTE 



Where 

Command Information 

is reserved and must be set to 0 

C/iaracters Per Line 

Valid numbers are 80 and 132. 

Lines Per Inch 

Valid numbers are 6 and 8. 

Returns 

None 

Remarks 

None 
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Category 5 - 
Function 44H 



PurDose 

Set Infinite Retry 




Parameter Packet Format 




Field 


Length 


Command Information 


BYTE 


Data Packet Format 


Field 


Length 


Data 


BYTE 



Where 

Command Information 

is reserved and must be set to 0 

Data 

The data is defined as: 

0 = Disable Infinite retry 

1 = Enable Infinite retry 

Returns 

None 

Remarks 

None 
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Category 5 - 
Function 46H 



Purpose 

Initialize Printer 




Parameter Packet Format 




Field 


Lengtli 


Command Information 


BYTE 


Data Packet Format 


Field 


Lengtii 


Set To 0 


BYTE 



The following fields are defined: 

Command Information 

is reserved and must be set to 0. 

Returns 

None 

Remarks 

None 



6-118 



Category 5 - 
Function 48H 



Purpose 

Activate Font 



Parameter Packet Format 



Field 


Length 


Command information 


BYTE 


iedi process. 


Field 


Length 


Code Page 


WORD 


Font ID 


WORD 



Where 

Command Information 

is reserved and must be set to 0. 

Code Page 

is tiie vaiue of the code page to make the currently active code 
page. 

OOOOH if the Code Page vaiue and Font ID are specified 

as 0 (0), set printer to hardware default code 
page and font. 

0001i-i-FFFFH Valid code page numbers. 

Font ID 

is the ID vaiue of the Font to maice currently active. 

OOOOIH If the Code Page value and Font ID are specified 

as 0 (0), set printer to hardware default code 
page and font. 

If font Id is 0 and the code page is a valid non-0, 
then any font is acceptable. 
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Category 5 - 
Function 48H 



0001H-FFFFH Valid font ID numbers, font types defined by the 
font file definitions for download fonts. For car- 
tridge fonts, font IDs are the numbers on the car- 
tridge label and are also entered in the DEVINFO 
statement for the printer. 

Returns 

IF AX = 0 NO error 
ELSE AX = Error Code 

FE02 Code page is not available 

FE03 No code page function because spooler not started 

FE04 Font ID is not available(verify) 

FE09 Error caused by switcher error not by input parameters 

FEOA Error caused by invalid printer name as input 

FEOD Got code page req when CP switcher not initialized 

FEOF PID table full cannot activate another entry 

FE13 DASD error reading font file control sequence section 

FE15 DASD error reading font file font definition block 

FE17 DASD error while writing to temporary spool file 

FE18 Disk full error while writing to temporary spool file 

FE19 Spool file handle was bad 

Remarks 

None 
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Category 5 - 
Function 62H 



Purpose 

Return Frame Control 
Parameter Packet Format 



Field 


Length 


Command Information 


BYTE 


Data Packet Format 


Field 


Length 


Characters per Line 


BYTE 


Lines per Incli 


BYTE 



Where 

Command Information 

is reserved and must be set to 0. 

Characters Per Line 

On return, field is set to 80 or 132. 

Lines Per Inch 

On return, field is set to 6 or 8. 

Returns 

None 



Remarks 

None 



Category 5 ~ 
Function 64H 



Purpose 

Return Infinite Retry 



Parameter Packet Format 



Field 


Length! 


Command Information 


BYTE 


Data Packet Format 


Field 


Length 


Data 


BYTE 


Where 




Command Information 

Is reserved and must be set to 0. 





Data 

On return, Data byte is set: 

0 = Infinite retry is disabled. 

1 = Infinite retry is enabled. 

Returns 

None 

Remarks 

None 
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Category 5 - 
Function 66H 



Puroose 

Return Printer Status 




Parameter Packet Format 




Field 


Lengtii 


Command Information 


BYTE 


Data Packet Format 


Field 


Length 


Data 


BYTE 



Where 

Command Information 

is reserved and must be set to 0. 
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Category 5 - 
Function 66H 



Data 

On return, Data byte is set: 



7 


3 t 






) '< 


I 1 


0 





































Returns 

None 

Remarks 

None 



1 = Timeout 
Unused 
Unused 
1 = I/O error 
1 = Selected 
1 = Out of Paper 
1 = Aclcnowledge 
1 = Not Busy 
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Category 5 - 
Function 69H 



Purpose 

Query Active Font 



Parameter Packet Format 



Field 


Length 


Command Information 


BYTE 


Data Packet Format 


Field 


Length 


Code Page 


WORD 


Font id 


WORD 



Where 

Command Information 

is reserved and must be set to 0. 

Code Page 

On return, is set to currentiy active code page. 

OOOOH if the Code Page value and Font iD are returned 

as 0 (0), the printer is set to the hardware default 
code page and font. 

0001H-FFFFH Valid code page numbers. 

font ID 

On return, is the ID value of the Font which Is currently active. 

OOOOH if the Code Page value and Font ID are specified 

as 0 (0), the printer is set to the hardware default 
code page and font. 

If font id is 0 and code page is non-0, no error will 
be returned if any font id is available for the 
specified code page. 
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Category 5 - 
Function 69H 



0001H-FFFFH Valid font Id numbers, font types defined by the 
font file definitions for download fonts. For car- 
tridge fonts, font IDs are the numbers on the car- 
tridge label and are also entered in the DEVINFO 
statement for the printer. 

Returns 

IF AX = 0 

then NO Error 

ELSE 

AX = Error Code 

FE03 No code page function because spooler not started 

FE09 Error caused by switcher error not by input parameters 

FEOA Error caused by invalid printer name as input 

FEOD Got code page req when CP switcher not initialized 

FE10 Received request for process ID not In PID table 

Remarks 

None 
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Category 5 - 
Function 6AH 



Purpose 

Verify that a particular code page and font is avaiiable for tlie speci- 
fied printer 



Parameter Packet Format 



Field 


Length 


Command Information 


BYTE 


Data Packet Format 


Field 


Length 


Code Page 


WORD 


Font Id 


WORD 



Where 

Command Information 

is reserved and must be set to 0. 

Code Page 

The Code Page number to validate. 

Values may be 0 to 65535. 
Font ID 

The Font ID value to validate. 

values may be 0 to 65535. The font ID is contained in the font file 
for download fonts. For cartridge fonts, font IDs are the numbers 
on the cartridge label and are also entered in the DEVINFO state- 
ment for the printer. 

Note: A value of 0 (0) for both the Code Page number and Font Id 
indicates the default hardware code page and font; this combination 
is always valid. 
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Category 5 - 
Function 6AH 



Returns 

IF AX = 0 

then NO Error 

ELSE 

AX = Error Code 

FE02 Code page is not available 

FE03 No code page function because spooler not started 

FE04 Font id is not available(verify) 

FEOA Error caused by invalid printer name as input 

FEOD Got code page req when CP switcher not initialized 

Remarks 

None 
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Category 7 Mouse Control lOCtI Commands 



Following Is a summary of Category 7 descriptions: 



Function 


I Description 


50H 


Allows Pointer Drawing after Screen Switch 


51H 


Notifies of Display Mode Change 


52H 


Notifies of Impending Session Switch 


53H 


Reassigns the Current Mouse Scaling Factors 


54H 


Assigns a New Mouse Event Mask 


56H 


Sets the Pointer Shape 


57H 


Frees the Mouse to Draw the Pointer anywhere on the 




Screen (unmark collision area) 


58H 


Restricts the Mouse from Pointer Drawing in Specified 




Area(s) of the Screen (mark collision area) 


59H 


Specifies/Replaces the Pointer Position 


5AH 


Specifies the Pointer Draw Device Driver Address (OS/2 




mode only) 


5BH 


Specifies the Pointer Draw Device Driver Address (DOS 




mode only) 


5CH 


Specifies a Subset of the Current Mouse Device Driver 




Status Flags 


60H 


Indicates the Number of Mouse Buttons Supported by the 




Device Driver 


61H 


Indicates the Mouse Setting for the Number of 




M Ickeys/CentI meter 


62H 


Indicates the Current Pointer Device Driver Status Flags 


63H 


Reads the Mouse Event Queue 


64H 


Indicates the Current Event Queue Status 


65H 


Indicates the Current Mouse Event Mask 


66H 


Indicates the Current Mouse Scaling Factors 


67H 


Indicates the Current Pointer Screen Position 


68H 


Indicates the Current Pointer Shape 
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Category 7 - 
Function 50H 



Purpose 

Allows Pointer Drawing after Session Switch 

Parameter Packet Format 

None 

Data Packet Format 

None 

Returns 

None 

Remarks 

This function has no Input or output parameter values. 

This function notifies the mouse device driver that a session switch 
has been completed and the pointer may now be drawn. 
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Category 7 - 
Function 51 H 



Purpose 

Notifies of Display Mode Cliange 



Parameter Packet Format 



Field 


Length 


Length 


WORD 


Type 


BYTE 


Color 


BYTE 


Text Column 


WORD 


Text Row 


WORD 


Graphics Column 


WORD 


Graphics Row 


WORD 



Data Packet Format 

None 

Where 

Length 

is an Input parameter to VioSetMode. Length specifies the length 
of the data structure in bytes Including Length Itself. The 
minimum structure size required is 3 bytes, and the maximum 
structure size required is 12 bytes. Any value specified for Length 
other than 3 must be an even number. If a structure of length less 
than the maximum is specified, OS/2 will use default values for 
the remaining fields. 

Type 

is a bit masl< that contain specifications for the mode being set. 
The definitions of the bits follow: 
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Category 7 - 
Function 51 H 



xxxxxxxb b = 0 monochrome compatible mode 
b = 1 other 

xxxxxxbx b = 6 text mode 

b = 1 graphics mode 
xxxxxbxx b = G enable color burst 

b = 1 disable color burst 

Color 

defines the number of colors as a power of 2. This is equlvaient to 
the number of color bits which define the color. For example, 

Color = 1 specifies 2 colors 
Color = 2 specifies 4 colors 
Color = 4 specifies 16 colors 
Color = 8 specifies 256 colors 

Color = 0 should be specified for 

monochrome modes 7, 7+, and F. 

Text Column 

are the number of text columns. 

Text Row 

are the number of text rows. 25 rows are supported for the color 
graphics adapter. Supported for the enhanced graphics adapter 
are rows 25 and 43. are Supported for the VGA adapter and the 
IBM Personal System/2 Display Adapter are rows 25 and 50. 

Graphics Column 

is the number of pel columns. 

Graphics Row 

is the number of pel rows. 



Returns 

None 
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Category 7 - 
Function 51 H 



Remarks 

When the Video Subsystem or registered Video Subsystem 
sets/resets the display mode, they must synchronize the mouse 
device driver pointer update routines by providing this notification 
record to the mouse device driver prior to switching display modes. 

The parameter packet is a far pointer to a Mode Data Definition 
record. 

This call returns no parameter values. 
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Category 7 - 
Function 52H 




Purpose 

Notifies of Impending Session Switch 




Parameter Packet Format 




Field 


Length 


Session Number 


WORD 


Switcli Notification Type 


WORD 



Data Packet Format 

None 



Where 

Session Number 

is the session number for notification action. This value must be 
in the range of 0 < = session number < = 
MaxNumberOfScreenGroups. The Global InfoSeg defines the 
valid range session ID's. 

Switch Notification Type 

is the switch notification type. The values for this parameter 
follow: 

Value Meaning 

-1 = The specified session number is terminating. 

> = 0 = The specified session number is being switched to. 

Returns 

None 

Remarks 

This function sets a system pointer draw enable/disable flag which 
does not allow pointer drawing until the flag is cleared via a 50H func- 
tion. 
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Category 7 - 
Function 53H 



Purpose 

Reassigns the Current Mouse Scaling Factors 



Parameter Packet Format 



Field 


Length 


Row Data 


WORD 


Column Data 


WORD 


Data Packet Format 

None 




Where 




Row Data 

Row coordinate scaling factor. 




Column Data 

Column coordinate scaling factor. 





The scaling factor values are positive integers in the range of: 
0 < value <= (32K-1) 

Returns 

None 

Remarks 

This function requires two 1-word caller-specified parameters. 

Scaling factors are ratio values that determine how much relative 
movement is necessary before the mouse device driver will report a 
mouse event. 
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Category 7 - 
Function 53H 



The ratios specify the number of mickeys per 8 pixels. The defauit 
ratio values are: 

Vertical/Row ration - 16 mickeys per 8 pixels 
Horizontal/Row ratio - 8 mickeys per 8 pixels. 
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Category 7 - 
Function 54H 



Purpose 

Assigns a New Mouse Event Mask 



Parameter Packet Format 



Field 


Length 


Event Mask 


WORD 


Data Packet Format 


None 




Where 




Event Mask 




Bit 


Meaning 


7-15 


Reserved = 0 


6 


Set if button 3 is down 


5 


Set if motion with button 3 down 


4 


Set if button 2 is down 


3 


Set if motion with button 2 down 


2 


Set if button 1 is down 


1 


Set if motion with button 1 down 


0 


Set if ali mouse motion, no buttons 



Returns 

None 

Remarks 

This function requires a caller-specified one word parameter con- 
taining the new mask for enabled/disabled device events. 
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Category 7 - 
Function 56H 



Purpose 

Sets the Pointer Shape 



Parameter Packet Format 



Field 


Length 


Buffer length 


WORD 


Columns 


WORD 


Rows 


WORD 


Column Hot Spot 


WORD 


Row Hot Spot 


WORD 



Data Packet Format 

The format is dependent on the mode of the display. Refer to the 
Remarks section in this call. 

Where 

Buffer lengtfi 

is the length of pointer image buffer. 

Columns 

is the width in columns of pointer image. 
Rows 

is the height in rows of pointer image. 

Column Hot Spot 

is the column offset within pointer image to hotspot. 

Row Hot Spot 

is the row offset within pointer image to hotspot. 

Returns 

None 
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Category 7 - 
Function 56H 



Remarks 

This function requires six caller specified parameters: 
Mono & Text 

Buffer length = (height in characters) * 

(width in characters) * 2 * 2 
= 1*1*2*2 

Note: For text mode height and width must be 1, so length is always 4. 
Graphics 

Buffer length = (height in pels) * 

(width in pels) * (bits per pel) * 2 / 8 

Note: Width (width in pels) must be a multiple of 8. 
Modes 4 & 5 (320 x 299) 

Buffer length = (height) * (width) * 2 * 2 / 8 
Mode 6 (648 x 296) 

Buffer length = (height) * (width) * 1 * 2 / 8 

Note: Length calculations produce byte boundary buffer sizes. 

All of the pointer definition record fields and the pointer shape buffer 
are validated using the session's mode table values. The parameter 
values must be the same orientation as the current session display 
mode: 

• graphics = pixel values 

• text = character values 

The data packet is a far pointer to an area in application storage con- 
taining the pointer image buffer. 

The pointer image buffer format is dependent on the mode of the 
display. For currently supported modes the buffer always consists of 
the "and pointer image data" followed by the "XOR pointer image 
data" The buffer always describes only one display plane. 

The parameter packet is a far pointer to an input pointer definition 
record. 
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Category 7 - 
Function 57H 



Purpose 

Frees the Mouse to Draw the Pointer anywhere on the Screen 

Parameter Packet Format 

None 

Data Packet Format 

None 

Returns 

None 

Remarks 

This function checl<s the pointer position, frees it if necessary, and 
allows it to draw anywhere on the screen. 
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Category 7 - 
Function 58H 



Purpose 

Restricts the Mouse from Pointer Drawing in Specified Area(s) of tlie 
Screen 



Parameter Packet Format 



Field 


Length 


Left Row Position 


WORD 


Left Column Position 


WORD 


Riglit Row Position 


WORD 


Right Column Position 


WORD 


Data Packet Format 

None 




Returns 

None 





Remarks 

This function requires one caller specified parameter. This param- 
eter is an address pointing to a 8-byte structured buffer. This buffer 
defines the collision area that will be protected from being over- 
written by system pointer draw operations. 

Values must be specified in either character or pixel values, 
depending on the current mode setting of the display. 

The data packet is a far pointer to an area in application storage 
I where a collision area definition record will be read by the mouse 
device driver. 

If the entire screen is specified, this function disables pointer drawing 
for the session. 
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Category 7 - 



Function 59H 




Purpose 

Specifies/Replaces the Pointer Position 




raraiiieier KaCKei rormai 




Field 


Length 


Row Position 


WORD 


Coiumn Position 


WORD 



Data Packet Format 

None 

Row Position 

The new row coordinate pointer screen position. 

Column Position 

The new coiumn coordinate pointer screen position. 

The coordinate vaiues are display mode dependent. Pixel values 
must be used If the display Is In graphics mode. Character posi- 
tion values must be used if the display is in text mode. 

Returns 

None 

Remarks 

This function does not override functions 57H and 58H. 

If the pointer is directed into a restricted area, it remains invisible 
until moved out of the area or until the area is freed of restrictions. 

The parameter paclcet is a far pointer to a structure in application 
storage where the mouse device driver will read coordinate posi- 
tions. 
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Category 7 - 
Functioin 5AH 



Purpose 

Specifies tlie Pointer Draw Device Driver Address (OS/2 mode only) 



Parameter Packet Format 


Field 


Length 


Pointer Entry 


DWORD 


Pointer DS 


DWORD 



Data Packet Format 

None 

Where 
Pointer Entry 

Contains two 1-word fields whose format is as follows: 
Word 0 = Pointer Draw Rtn Device Driver's Entry Point Offset 
Word 1 = Pointer Draw DD Entry Point Selector 
Pointer DS 

Contains two 1-word fields whose format is as follows: 
Word 0 = Reserved = 0 

Word 1 = Pointer Draw Rtn Device Driver's Data Segment 
selector 

Returns 

None 
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Category 7 - 
Function 5AH 



Remarks 

This parameter packet is a far pointer to a structure in application 
storage where the mouse device driver will read the selector : offset 
of the entry point of the session's pointer draw routine. The pointer 
image draw routine Is an installed pseudo character device driver. 
The mouse router/handler must: 

• OPEN the pointer draw device driver. 

• Query the pointer draw device driver for the address of its entry 
point. 

• Pass the resulting address of the pointer draw entry point to the 
mouse device driver using the lOCtI described above. 

The mouse device driver issues a far call to the pointer draw device 
driver when ever a mouse Interrupt occurs that requires action con- 
cerning the pointer image. 

In addition, the mouse device driver may call the pointer draw routine 
as a result of some action on the part of the application, such as: 

• MouDrawPtr 

• MouRemovePtr 

• MouSetPtrPos 

• MouSetPtrShape 

• MouGetPtrShape 

This function Is applicable In the OS/2 mode only. 
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Category 7 - 
Function 5BH 



Purpose 

Specifies tlie Pointer Draw Device Driver Address (DOS mode only) 



Parameter Packet Format 


Field 


Length 


Pointer Entry 


DWORD 


Pointer DS 


DWORD 



Data Packet Format 

None 

Where 

Pointer Entry 

Contains two 1-word fields wliose format is: 

Word 0 = Pointer Draw Rtn Device Driver's Entry Point Offset 
Word 1 = Pointer Draw Rtn Device Driver's Entry Point 
Selector 

Pointer DS 

Entry contains two 1-word fields wliose format is: 
Word 0 = Reserved = 0 

Word 1 = Pointer Draw Rtn Device Driver's Data Segment 
Selector 

Returns 

None 
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Category 7 - 
Function 5BH 



Remarks 

This lOCtI is for the DOS execution environment only. 

This is the same structure passed by the OS/2 lOCti. 

This lOCtI is issued by the Sheli/Session Manager at the end of 
Syslnit. 

The cali passes to the mouse device driver the address of the entry 
point of a pointer draw routine for DOS execution environment 
display support. 

The data is passed as (selector : offset) pairs. The DOS execution 
environment portion of the device driver uses the VirtToPhys and 
PhysToVirt OS/2 calls to convert this address to the (segment : offset) 
real address for use in the DOS execution environment. 

The parameter packet is a far pointer to a structure in application 
storage where the mouse device driver will read the selector : offset 
of the entry point of the DOS execution environment session's pointer 
draw routine. 
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Category 7 - 
Function 5CH 



Purpose 

Specifies a Subset of the Current Mouse Device Driver Status Fiags 



Parameter Packet Format 



Field 


Length 


Status Mask 


WORD 



Data Packet Format 

None 

Where 

Status Mask 

is defined with the bit level definitions as follows: 

High Byte 

Bit Meaning 

7-2 Reserved = 0 

1 Set if mouse data returned in miclteys, not display units 

0 Set if the interrupt level pointer draw routine is not called 

Low Byte 

Bit Meaning 

7-0 Reserved = 0 

A set bit is a value of 1. 

Returns 

None 
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Category 7 - 
Function 5CH 



Remarks 

This function is the complement to 62H. 

The parameter packet is a far pointer to an application area where 
the Mouse Device Driver will read a one-word input device status 
mask. Only the high byte of this one-word device status mask may be 
set. 
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Category 7 - 
Function 60H 



Purpose 

Indicates Number of Buttons Supported by the Device Driver 



Parameter Packet Format 

None 




Data Packet Format 




Field 


Length 


Number Supported 


WORD 



Where 

Number Supported 

the data paclcet is a far pointer to word in application storage 
where the mouse device driver will write a one-word return value. 
Return values will be In the range of: 

1 = one-button support 

2 = two-button support 

3 = three-button support 

Returns 

None 

Remarks 

This function requires a caller-specified address designating where 
the device driver can write a one-word return value. 
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Category 7 - 
Function 61 H 



Purpose 

indicates Mouse Setting for tlie Number of Miclteys/Centi meter 



Parameter Packet Format 

None 




Data Packet Format 




Field 


Length 


MIclceys/Centimeter 


WORD 



Where 

MickeyslCentiiTiBter 

the data pacicet is a far pointer to a word in appiication storage 
wliere tlie mouse device driver wiii write a return value. Return 
values will be in the range of: 

0 < number of mickeys/centi meter < = (32K - 1) 

Returns 

None 

Remarks 

None 
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Category 7 - 
Function 62H 



Purpose 

Indicates the Current Pointer Device Driver Status Flags 



Parameter Packet Format 

None 




Data Packet Format 




Field 


Length 


Status Flags 


WORD 



Where 

status Flags 

High Byte 

B/t Meaning 

7-2 Reserved = 0 

1 Set if mouse data returned in micl<eys 

0 Set if the interrupt level pointer draw routine is not called 

Low Byte 

Bit Meaning 

7-4 Reserved = 0 

3 Set If pointer draw routine disabled by unsupported mode 

2 Set if flush in progress 

1 Set if block read in progress 

0 Set if event queue busy with I/O 

A set bit is a value of 1 . 

Returns 

None 
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Category 7 - 
Function 62H 



Remarks 

The data packet is a far pointer to a word in application storage 
where the mouse device driver will write a one-word return value. 
Return values have the following meaning: 

This function is the complement to 5CH. 
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Category 7 - 
Function 63H 



Purpose 

Reads the Mouse Event Queue 



Parameter Packet Format 



Field 


Length 


Read Type 


WORD 


Data Packet Format 


Field 


Length 


Event Mask 


WORD 


Time 


DWORD 


Row Position 


WORD 


Column Position 


WORD 



Where 

Read Type 

is oniy used to determine the type of action to be taken if no event 
queue data is available. The values may be: 

0 = Blocl( the process (Wait) until event data is available 

1 = Return a NULL record (No Wait) for the request. 

The data pacicet is a far pointer to an event queue element record 
structure in application storage to be written into. 

Event Mask 

(See function 65H) 

7/fne 

is Event time stamp in milliseconds 
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Category 7 - 
Function 63H 



Row Position 

is Pointer row coordinate 

Column Position 

is Pointer column coordinate 

Returns 

None 

Remarks 

This function requires two caller-specified parameters: 

1. An address wliere tlie Mouse Device Driver will write the event 
queue's FIFO element 10-byte record contents. 

2. A one-word value indicating the type of read operation to be per- 
formed. The read type is only used to determine the type of 
action to be taken if no event queue data is available. 
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Category 7 - 
Fimction 64H 



Purpose 

Indicates the Current Event Queue Status 




Parameter Packet Format 

None 




Data Packet Format 




Field 


Length 


Element Number 


WORD 


Queue Number 


WORD 



Where 

Element Number 

is where the mouse device driver will write the current number of 
event queue elements. The return value is a one-word value in 
the range of: 

0 < = value < = MaxNumQueueElements. 

Queue Number 

is where the mouse device driver will write a one-word return 
value for the MaxNumQueueElements. 

Returns 

None 

Remarks 

This function returns both the current number of queued elements in 
the event queue and the maximum number of elements allowed in an 
event queue. 
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Category 1 - 
Function 65H 




Purpose 

Indicates the Current Mouse Event Mask 




Parameter Packet Format 

None 




Data Packet Format 




Field 


Length 


Event Mask 


WORD 



Where 

Eirenf Mask 

has the following bit level definitions: 





ibfean/ng 


7-15 


Reserved = 0 


6 


Set if button 3 is down 


5 


Set if nnotion with button 3 down 


4 


Set if button 2 is down 


3 


Set if motion with button 2 down 


2 


Set if button 1 is down 


1 


Set if motion with button 1 down 


0 


Set if all mouse motion, no buttons 



Returns 

None 

Remarks 

This function requires a caller specified address designating where 
the mouse device driver will write a one-word return value. The 
return values could be any valid combination of enabled/disabled 
event flags. 
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Category 7 - 
Function 66H 



Purpose 

Indicates the Current Mouse Scaling Factors 



Parameter Packet Format 




None 




Data Packet Format 




Field 


Length 


Row Data 


WORD 


Column Data 


WORD 



Where 

Row data 

Is the row coordinate scaling factor. 

Column data 

is the column coordinate scaling factor. 

The scaling factor values are positive integers in the range of: 
0 < value < = (32K - 1) 

Returns 

None 

Remarks 

This call does not require input parameters. This function requires 
one caller specified address. The mouse device driver will place a 
one-word return value at each of the given addresses. 

• The first address will receive the row coordinate scaling factor 

• The second address will receive the column coordinate scaling 
factor. 
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Category 7 - 
Function 66H 



The scaling factor values are positive integers in the range of: 
0 < value < = (32K - 1) 

The data packet is a far pointer to a two-word structure in application 
storage where the mouse device driver will write two one-word return 
values. 
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Category 7 - 
Function 67H 



Purpose 

Indicates the Current Pointer Screen Position 



Parameter Packet Format 

None 




Data Packet Format 




Field 


Length 


Row Position 


WORD 


Coiumn Position 


WORD 



Where 

Row Position 

Row coordinate pointer screen position- 
Column Position 

Column coordinate pointer screen position. 

The coordinate values are display mode dependent. Pixel values 
are returned if the display is in graphics mode. Character position 
values are returned if the display is in text mode. 

Returns 

None 

Remarks 

This call does not require input parameters. The data packet is a far 
pointer to a structure in application storage where the mouse device 
driver will write coordinate positions- 
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Category 7 - 
Function 68H 



Purpose 

Indicates the Current Pointer Sliape 



Parameter Packet Format 



Field 


Length 


Buffer Length 


WORD 


Columns 


WORD 


Rows 


WORD 


Column Hot Spot 


WORD 


Row Hot Spot 


WORD 


Data Packet Format 


Field 


Length 


FAR Pointer 


DWORD 



Where 

Buffer Lengtfi 

Length of pointer image buffer 

Exit Error: If the Input Buffer Length value is smaller than the 
required storage to perform the data copy then the Buffer Length 
field will be returned with the minimum required pointer shape 
buffer length. An error code is also returned for an invalid param- 
eter 

Exit Normal: if the input Buffer Length value is greater than or 
equal to the amount of storage required for the pointer shape 
image then the current pointer information is returned in the 
pointer data record and the pointer shape image data is copied 
into the user specified Data address. 
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Function 68H 



Columns 

Width in columns of pointer image 

Rows 

Height in rows of pointer image 

Column Hot Spot 

Column offset within pointer image to hotspot 

Row Hot Spot 

Row offset within pointer image to hotspot 

Returns 

On Input the only pointer definition record field used by the mouse 
device driver is the Buffer Length field. The Buffer Length value must 
specify the length of the user provided shape buffer, pointed to by the 
Data parameter address. 

Remarks 

This buffer is described by the pointer definition record and for 
normal conditions consists of the Screen AND and Pointer XOR 
masks. 
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category 8 Logical Disk Control lOCtI Commands 

Following 1$ a summary of Category 8 descriptions: 
Function Description 



OOH Lock drive 

01 H Unlocl( drive 

02H Redetermine media 

03H Set logical map 

20H Blocl( removable 

21H Get logical map 

22H Reserved 

43H Set device parameters 

44H Write track 

45H Format and verify track 

5FH Reserved 

63H Get device parameters 

64H Read track 

65H Verify track 



6-162 



Category 8 - 
Function OOH 



Purpose 

Lock Drive 

The operation of lodging a drive is used to exclude I/O by another 
process on the volume in the drive. The Lock Drive call will 
succeed only if there is one file handle open on the volume in the 
drive; that is, the file handle on which this DosDevlOCtI call is 
issued. This is necessary since the desired result is to exclude all 
other I/O to this volume until the Unlock Drive call is issued. 



Parameter Packet Format 



Field 


Length 


Command Information 


BYTE 


Data Packet Format 


Field 


Length 


Set To 0 


BYTE 



Where 

Command Information 

Is reserved and must be set to 0. 

Returns 

None 

Remarks 

None 
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Category 8 - 
Function 01 H 



Unlock Drive 




Parameter Packet Format 




Field 


Length 


CommancI Information 


BYTE 


Data Packet Format 


Field 


Length 


Set To 0 


BYTE 



Where 

Command Information 

is reserved and must be set to 0. 

Returns 

None 

Remarks 

The locl<ed volume represented by the file handle on which this 
DosDevlOCtI call is issued must be in the drive. 
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Category 8 - 
Function 02H 



Purpose 

Redetermine Media - Tliis function causes OS/2 to re-generate the 
internal ID for the volume currently in the drive, and associate this ID 



with the specified handle. 




Parameter Packet Format 




Field 


Length 


Command Information 


BYTE 


Data Packet Format 


Field 


Length 


Set To 0 


BYTE 



Where 

Command Information 

is reserved and must be set to 0. 

Returns 

None 

Remarks 

The caller must have the disk or diskette locked when calling this 
function. Otherwise, the call will fail with the error 
ERROR_LOCK_VIOLATION. 

The caller can have only one file open to refer to the disk or diskette. 
If other processes have the volume open, or the calling process has 
opened the volume multiple times, the call will fail returning 
ERROR_DRIVE_BUSY. 



6-165 



Category 8 - 
Function 03H 



I U 1 |# WW w 

Set Logical Map 




Parameter Packet Format 




Field 


Length 


Command information 


BYTE 


Data Packet Format 


Field 


Length 


Logical Drive Number 


BYTE 



Where 

Command Information 

is reserved and must be set to 0. 

Logical Drive Number 

on entry logical drive number (1 = A, 2=8, etc) is specified. 

on return, this byte specifies the logical drive currently mapped to 
the drive that the specified file handle is opened on. A 0 is 
returned if there is only one logical drive mapped onto this phys- 
ical drive. 



Returns 

None 

Remarks 

None. 
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Category 8 - 
Function 20H 



Purpose 

Block Removable 




Parameter Packet Format 




Field 


Length 


Command Information 


BYTE 


Data Packet Format 


Field 


Length 


Data 


BYTE 



Where 

Command Information 

Is reserved and must be set to 0. 

Data 

on return, the data byte is set accordingly: 

0 = removable media 

1 = nonremovable media 

Returns 

None 

Remarks 

None 
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Category 8 - 
Function 21 H 



Purpose 

Get Logical Map 



Parameter Packet Format 



Field 


Length 


Command Information 


BYTE 


Data Packet Format 


Field 


Length 


Logical Drive Number 


BYTE 


Where 




Command Information 

is reserved and must be set to 0. 




Logical Drive Number 

on entry Logical Drive Number (1 


= A, and others). 



on return this byte is filled with the logical drive is currently 
mapped to the drive the specified handle is opened on. A 0 is 
returned If there is only one logical drive mapped onto this phys- 
ical drive. 



Returns 

None 

Remarks 

None 
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Category 8 - 
Function 43H 



Purpose 

Set Device Parameters 



Parameter Packet Format 



Field 


Length 


Command Information 


BYTE 


Data Packet Format 


Field 


Lengtli 


Extended BPB for devices 


31 BYTES 


Number of cylinders 


WORD 


Device type 


BYTE 


Device attributes 


WORD 



Wliere 

Command Information 

the two low bits of the command byte are used to indicate one of 
three possible actions: 

Bit 

Values Description 

00 Revert to building the BPB off the medium for all subse- 
quent Build BPB calls. This is used to reset the device 
parameters back to their original state. 

01 Change the default BPB for the physical device. This is 
not used for the medium and should be used with 
caution. 
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Category 8 - 
Function 43H 



10 Change the BPB for the medium to the specified BPB 

and return the new BPB as the BPB for the medium for 
ail subsequent Build BPB calls. This is used for the 
initial set device parameters of the medium. 

All other bits are reserved and must be set to 0. 

Extended BPB 

The extended BPB has the following format: 



Field 


Length 


Bytes Per Sector 


WORD 


Sectors Per Cluster 


BYTE 


Reserved Sectors 


WORD 


Number of FATs 


BYTE 


Root DIr Entries 


WORD 


Total Sectors 


WORD 


Media Descriptor 


BYTE 


Sectors Per FAT 


WORD 


Sectors Per Tracl< 


WORD 


Number Of Heads 


WORD 


Hidden Sectors 


DWORD 


Large Total Sectors 


DWORD 


Reserved 


6 BYTES 



Number of cylinders 

indicates the number of cylinders defined for the physical device. 

Device type 

field describes the physical layout of the device specified, it tal<es 
one of the f ol I owl ng val ues: 
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Function 43H 



Value Meaning 

0 48 TPI low density diskette drive 

1 96 TP! high density dislcette drive 

2 Small (3 1/2 inch) (720KB) drive 

3 8 Inch Single Density floppy drive 

4 8 Inch Double Density floppy drive 

5 Fixed disk 

6 Tape drive 

7 Other (other type of device) 

Device attributes 

The device attributes is a bit field that returns various flag infor- 
mation about the specified drive: 

Bit Description 

0 Removable media flag. If set, the media can be changed 

1 Changeline flag. If set, the media cannot be removed. 
All other bits are reserved and must be set to 0. 



Returns 

None 

Remarks 

None 
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Category 8 - 
Functions 44H, 64H, 65H 



Purpose 

Write Track, Read Track, Verify Track. 

These commands have the same parameter packet. 



Parameter Packet Format 



Field 


Length 


Command Information 


BYTE 


Head 


WORD 


Cylinder 


WORD 


First Sector 


WORD 


Number of sectors 


WORD 


Track Layout field 


BYTES 



Data Packet Format 

The data packet is a buffer. For the write call it contains the data to 
be written. For a read call the buffer must be large enough to hold 
requested data. For the verify call the data packet is not used. 



Field 


Length 


Buffer 


BYTES 
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Category 8 - 
Functions 44H, 64H, 65H 



Where 

Command Information 

is a bit field as follows: 

Bit Description 

0 Clear - Track layout contains non-consecutive sectors or 
does not start with sector 1 

Set - Track layout starts with sector 1 and contains only 
consecutive sectors 

Reserved All other bits are reserved and must be set to 0. 

Head 

is the physical head on the drive to perform the operation. 
Cylinder 

Is the cylinder for the read/write/verify. 
First Sector 

is the logical sector number within the track layout table to start 
the I/O operation. 

Note that the sector numbers are based from 0. (For example, 
the third sector is numbered 2.) 

Number of Sectors 

is the number of sectors to read/write/verify (up to the 
maximum specified in the track table - the lOCtI subfunctions 
will not step heads/tracks). 
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Category 8 - 
Functions 44H, 64H, 65H 



Track layout field 
is as follows: 



Field 


Length 


Sector number for sector 1 


WORD 


Sector size for sector 1 


WORD 


Sector number for sector 2 


WORD 


Sector size for sector 2 


WORD 


Sector number for sector 3 


WORD 


Sector size for sector 3 


WORD 




Sector number for sector n 


WORD 


Sector size for sector n 


WORD 



Returns 

None 

Remarks 

This call performs the operation on the device that is specified in 
this request. The tracl< table passed in on the call is used to deter- 
mine the sector number which is passed on to the disk controller for 
the operation. In cases where the sectors are oddly numbered or are 
non-consecutive, we break this request into N single sector oper- 
ations and read/write/verify one sector at a time. Note also that the 
device driver will NOT correctly read a non-512 byte sector if the read 
operation would generate a DMA violation error. Application writers 
must be careful to make sure that this error does NOT occur. 

The sector table that is specified is used to provide information that is 
used during the READ/WRITEA/ERIFY track operations. 
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Category 8 ~ 
Function 45H 



Purpose 

Format and Verify a Track on a Drive 
Parameter Packet Format 



Field 


Length 


Command information 


BYTE 


Head 


WORD 


Cyiinder 


WORD 


Reserved 


WORD 


Number of sectors 


WORD 


Format Tracl^ Tabie 


BYTES 


Data Packet Format 


Field 


Length 


Set To 0 


BYTE 



Where 

Tiie foilowing fields are defined: 

Command Information 

is a bit fieid as follows: 

Bit Description 

0 Clear - Track layout contains non-consecutive sectors or 
does not start with sector 1 

Set - Track layout starts with sector 1 and contains only 
consecutive sectors 

Ail other bits are reserved and must be set to 0. 
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Category 8 - 
Function 45H 



Head 

is the physical head on the drive to perform the operation. 

Cylinder 

is the cylinder for the operation. 

Number of Sectors 

is the number of sectors on the tracl< being formatted. 

Format Track Table 

is the format track table contains four byte tuples. Each tuple is in 
the form (c,h,r,n) with c = cylinder number, h = head number, r 
= sector Id, and n = bytes per sector. 

n bytes I sector 

0 128 

1 256 

2 512 

3 1024 

Returns 

None 

Remarks 

This routine formats and verifies the track specified according to the 
information passed in the Track Layout field. The track layout is 
passed to the controller and the controller performs the formatting. 
Note that some controllers do NOT support formatting tracks with 
varying sector sizes, so in general the application writer must take 
care to be sure that the sector sizes specified in the Track Layout 
table are all the same. 

There is a 4-tuple for each sector in the track to be formatted. Both 
the head and cylinder numbers must be consistent within the tuple 
and with the corresponding parameter packet field. 
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Category 8 - 
Function 63H 



Purpose 

Get Device Parameters 



Parameter Packet Format 



Field 


Length 


Command Information 


BYTE 


Data Packet Format 


Field 


Length 


Extended BPB for device 


31 BYTES 


Number of cylinders 


WORD 


Device type 


BYTE 


Device attributes 


WORD 



Where 

The following fields are defined: 

Command Information 
is a bit field as follows: 

For bit 0: 

Value Description 

0 Return the recommended BPB for the drive. The recom- 
mended BPB for the drive is the BPB for the physical 
device. 

1 Return the BPB for the media currently in the drive 

Extended BPB for device 

The device driver maintains two BPB's for each drive, one is the 
current BPB (that corresponds to the media in the drive), and the 
other is a recommended BPB that is based on the type of media 
that corresponds to the physical device (for a high density drive, 
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Category 8 - 
Function 63H 

that is a BPB for a 96 tracks-per-inch (TPI) floppy, for a low 
density drive it is the BPB for a 48 TPI floppy, etc). The low bit of 
the command information field indicates which BPB the applica- 
tion would like to see. 

Number of cylinders 

The number of cylinders indicates the number of cylinders defined 
for the physical device. 

Device type 

The device type field describes the physical layout of the device 
specified. It takes one of the following values: 

Value Meaning 



0 


48 TPI low density diskette drive 


1 


96 TPI high density diskette drive 


2 


Small (3 1/2 inch) (720KB) diskette drive 


3 


8 Inch Single Density diskette drive 


4 


8 Inch Double Density diskette drive 


5 


Fixed disk 


6 


Tape drive 


7 


Other (other type of device) 



Device attributes 

The device attributes is a bit field that returns various flag infor- 
mation about the specified drive: 

Bit Description 

0 Removable media flag If set, the media can be changed 

1 Changeline flag If set, the media cannot be removed 

Returns 

None 

Remarks 

All other bits are reserved and must be set to 0. 
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Category 9 Physical Disk Control lOCti Commands 



Category 9 is a category which is used to access physical 
partltionable fixed dislcs. 

The handle, used for Category 9 commands is the handle returned by 
the DosPhysicalDlsk (function 2) API function call. This handle is 
used to tell the system which physical disk the lOCtI command is for. 

The physical disk control commands relate to the entire partltionable 
fixed disk. Direct track and sector I/O begin at the beginning of the 
physical drive. Function 63H, get physical device parameters, 
describes the entire physical device. 

Following is a summary of Category 9 descriptions: 



Function Description 

OOH Lock physical drive 

01 H Unlock physical drive 

44H Physical write track 

63H Get physical device parameters 

64H Physical read track 

65H Physical verify track 
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Category 9 - 
Function OOH 



Purpose 

Lock Physical Drive 




Parameter Packet Format 




Field 


Length 


Command Information 


BYTE 


Data Packet Format 


Field 


Lengtli 


Set To 0 


BYTE 



Where 

Command Inlormatlon 

is reserved and must be set to 0. 

Returns 

None 

Remarks 

All the logical units on the physical drive are affected as well. 
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Category 9 - 
Function 01 H 



PufDOse 

Unlock Physical Drive 




Parameter Packet Format 




Field 


Length 


Command Information 


BYTE 


Data Packet Format 


Field 


Length 


Set To 0 


BYTE 



Where 

Command Information 

is reserved and must be set to 0. 

Returns 

None 

Remarks 

All the logical units on the physical drive are affected as well. 
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Category 9 - 
Functions 44H, 64H, 65H 



Purpose 

Physical Write Track, Physical Read Track, Physical Verify Track 



Parameter Packet Format 

These commands have the same parameter packet. 



Field 


Length 


Command Information 


BYTE 


Head 


WORD 


Cylinder 


WORD 


First Sector 


WORD 


Number of sectors 


WORD 


Track Layout Table 


BYTES 



Data Packet Format 

The data packet is a buffer. For the WRITE call It contains the data to 
be written. For a READ call the buffer must be large enough to hold 
requested data. For the VERIFY call the data packet Is not used. 



Field 


Length 


Buffer 


BYTES 


Where 




Command Information 




is a bit field as follows: 




Bit Description 





0 0 (Clear) - Track layout contains non-consecutive 

sectors or does not start with sector 1 
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Category 9 - 
Functions 44H, 64H, 65H 



1 (Set) - Track layout start with sector 1 and contains 
only consecutive sectors 
All other bits are reserved and must be 0. 

Head 

is the physical head on the drive to perform the operation. 
Cylinder 

Is the cylinder for the read/write/verify. 
First Sector 

is the logical sector number within the track layout table to start 
the I/O operation. 

Note that the sector numbers are based from 0. (For example, 
the third sector is numbered 2.) 

Number of Sectors 

The number of sectors to read/write/verify (up to the maximum 
specified in the track table - the iOCtI subfunctions will NOT step 
heads/tracks). 

Track Layout Table 

The track layout table is as follows: 



Field 


Length 


Sector number for sector 1 


WORD 


Sector size for sector 1 


WORD 


Sector number for sector 2 


WORD 


Sector size for sector 2 


WORD 


Sector number for sector 3 


WORD 


Sector size for sector 3 


WORD 




Sector number for sector N 


WORD 



6-183 



Category 9 - 




Functions 44H, 64H, 65H 




Field 


Length 


Sector size for sector N 


WORD 


Returns 




None 





Remarks 

This call will perform the operation on the physical drive that is speci- 
fied in this request. It works like the similar Category 8 command 
except that the I/O is done offset from the beginning of the physical 
drive instead of from the beginning of the extended volume associ- 
ated with the unit number (category 8). 

The track table passed in on the call is used to determine the sector 
number which is passed on to the disk controller for the operation. In 
cases where the sectors are oddly numbered or are non-consecutive 
the request is broken into N single sector operations, and 
read/written/verified one sector at a time. Note also that the device 
driver will not correctly read a non 512 byte sector if the read opera- 
tion would generate a DMA violation error. Application writers must 
be careful to make sure that this error will not occur. 

The sector table that is specified is used to provide information that is 
used during the READ/WRITEA/ERIFY track operations. 
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Category 9 - 
Function 63H 



Purpose 

Get Physical Device Parameters 



Parameter Packet Format 



Field 


Length 


Command Information 


BYTE 


Data Packet Format 


Field 


Length 


Reserved 


WORD 


Number of Cylinders 


WORD 


Number of Heads 


WORD 


Number of Sectors per Track 


WORD 


Reserved 


WORD 


Reserved 


WORD 


Reserved 


WORD 


Reserved 


WORD 



Where 

Command Information 

Is reserved and must be set to 0. 

Number of Cylinders 

is where the number of cylinders on the physical drive are 
returned. 

Number of Heads 

is where the number of heads on the physical drive are returned. 
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Category 9 - 
Function 63H 



Number of Sectors per Track 

is where the number of sectors per track on the physical drive are 
returned. 

Returns 

None 

Remarks 

The data values returned apply to the entire physical disk. 
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Category 10 Character Device Monitor lOCtI 
Commands 

Following Is a summary of Category 10 descriptions: 

Function Description 

40H Register a Monitor 



Category 10 - 
Function 40H 



Purpose 

Register a Monitor 



Parameter Packet Format 



Field 


Length 


Command Information 


BYTE 


Data Packet Format 


Field 


Length 


Placement flag 


WORD 


Index 


WORD 


Address of input buffer 


DWORD 


Offset of output buffer 


WORD 



Where 

Command Information 

is reserved and must be set to 0. 

Placement flag 

is tlie parameter described in DosMonReg. Values can be 0, 1, or 
2. 

Index 

is a device driver dependent field. 

Address of input buffer 

\s the monitor input buffer initialized by the monitor dispatcher 
and used by DosMonRead. 

Offset of output buffer 

is the monitor output buffer initialized by the monitor dispatcher 
and used by DosMonWrite. 
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Category 10 - 
Function 40H 



Note: Refer to DosMonRead, DosMonReg and DosMonWrite in 
Chapter 2, for additional information concerning tlie device monitor. 

Returns 

None 

Remarks 

Tliese fields are used by the device drivers to formulate the 
MonRegister calls (DevHIp). 
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Category 11 General Device Control lOCtI 
Commands 



Following Is a summary of Category 11 descriptions: 

Function Description 

01H Flush Input buffer 

02H Flush output buffer 

60H Query monitor support 
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Category 11 - 
iFunction Ol H 



Flush Input Buffer. 




Parameter Packet Format 




Field 


Length 


Command Information 


BYTE 


Data Packet Format 


Field 


Length 


Set To 0 


BYTE 



Where 

Command Information 

Is reserved and must be set to 0. 

Returns 

None 

Remarks 

None 
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Category 11 - 
Function 02H 



riirpose 

Flush output buffer. 




Parameter Packet Format 




Field 


Length 


Command Information 


BYTE 


Data Packet Format 


Field 


Length 


Set To 0 


BYTE 



Where 

Command Information 

is reserved and must be set to 0. 

Returns 

None 

Remarks 

None 
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Category 11 - 
Function 60H 



Purpose 

Query monitor support. 




Parameter Packet Format 




Field 


Length 


Command Information 


BYTE 


Data Packet Format 


Field 


Length 


Set To 0 


BYTE 



Where 

Command Information 

is reserved and must be set to 0. 

Returns 

None 

Remarks 

This request is used to query a device driver for monitor support. 

The device driver should return the system error, 
Monitors-Not-Supported, if it does not support character monitors. If 
monitors are supported, then it should return No-Error (OOH). 



6-193 



6-194 



Appendix A. IBM OS/2 Return Codes 

Number/Return Code/Definition 

0 NO_ERROR 

no error occurred 

1 ERROR_INVALID_FUNCTION 

invalid function number 

2 ERROR_FILE_NOT_FOUND 

file not found 

3 ERROR_PATH_NOT_FOUND 

path not found 

4 ERROR_TOO_MANY_OPEN_FILES 

too many open files (no handles left) 

5 ERROR_ACCESS_DENIED 

access denied 

6 ERRORJNVALID_HANDLE 

invalid handle 

7 ERROR_ARENA_TRASHED 

memory control bloclcs destroyed 

8 ERROR_NOT_ENOUGH_MEMORY 

insufficient memory 

9 ERRORJNVALID_BLOCK 

invalid memory block address 

10 ERROR_BAD_ENVIRONMENT 

invalid environment 

11 ERROR_BAD_FORMAT 

invalid format 

12 ERROR_INVALID_ACCESS 

invalid access code 

13 ERROR_INVALID_DATA 

invalid data 

14 Reserved 

75 ERRORJNVALID_DRIVE 

invalid drive was specified 

16 ERROR_CURRENT_DIRECTORY 

attempt to remove current directory 

17 ERROR_NOT_SAME_DEVICE 

not same device 

18 ERROR_NO_MORE_FILES 

no more files 



19 ERROR_WRITE_PROTECT 

attempt to write on write protected diskette 

20 ERROR_BAD_UNIT 

unknown unit 

21 ERROR_NOT_READY 

drive not ready 

22 ERROR_BAD_COMMAND 

unknown command 

23 ERROR_CRC 

data error (CRC) 

24 ERROR_BAD_LENGTH 

bad request structure length 

25 ERROR_SEEK 

seek error 

26 ERROR_NOT_DOS_DISK 

unknown media type 

27 ERROR_SECTOR_NOT_FOUND 

sector not found 

28 ERROR_OUT_OF_PAPER 

printer out of paper 

29 ERROR_WRITE_FAULT 

write fault 

30 ERROR_READ_FAULT 

read fault 

31 ERROR_GEN_FAILURE 

general failure 

32 ERROR_SHARING_VIOLATION 

sharing violation 

33 ERROR_LOCK_VIOLATION 

lock violation 

34 ERROR_WRONG_DISK 

invalid disk change 

35 ERROR_FCB_UNAVAILABLE 

FOB unavailable 

36 ERROR_SHARING_BUFFER_EXCEEDED 

sharing buffer overflow 
37-49 Reserved 
50 ERROR_NOT_SUPPORTED 

network request not supported 
65 ERROR_NETWORK_ACCESS_DENIED 

access denied 
73-79 Reserved 
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80 ERROR_FILE_EXISTS 

file exists 

81 ERROR_DUP_FCB 

Reserved 

82 ERROR_CANNOT_MAKE 

cannot malce directory entry 

83 ERROR_FAILJ24 

fail on INT 24 

84 ERROR_OUT_OF_STRUCTURES 

too many redirections 

85 ERROR_ALREADY_ASSIGNED 

duplicate redirection 

86 ERRORJNVALID_PASSWORD 

invalid password 

87 ERRORJNVALID_PARAMETER 

invalid parameter 

88 ERROR_NET_WRITE_FAULT 

network device fault 

89 ERROR_NO_PROC_SLOTS 

no process slots available 

90 ERROR_NOT_FROZEN 

system error 

91 ERROR_TSTOVFL 

timer service table overllow 

92 ERROR.TSTDUP 

timer service table duplicate 

93 ERROR_NOJTEMS 

no items to work on 
95 ERRORJNTERRUPT 

interrupted system call 

100 ERROR_TOO_MANY_SEMAPHORES 

hit user/open semaphore limit exceeded 

101 ERROR_EXCL_SEM_ALREADY_OWNED 

exclusive semaphore already owned 

102 ERROR_SEM_IS_SET 

SemClose found semaphore set 

103 ERROR_TOO_MANY_SEM_REQUESTS 

too many exclusive semaphore requests 

104 ERRORJNVALID_ATJNTERRUPT_TIME 

operation invalid at Interrupt time 

105 ERROR_SEM_OWNER_DIED 

previous semaphore owner terminated without freeing 
semaphore 
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106 ERROR_SEM_USER_LIMIT 

semaphore limit exceeded 

107 ERROR_DISK_CHANGE 

insert drive B 6\sk into drive A 

108 ERROR_DRIVE_LOCKED 

drive locked by anotiier process 

109 ERROR_BROKEN_PIPE 

write on pipe with no reader 

110 ERROR_OPEN_FAILED 

open/create failed due to explicit fail command 

111 ERROR_BUFFER_OVERFLOW 

buffer passed to system call too small to hold return data 

112 ERROR_DISK_FULL 

not enough space on the disk 

113 ERROR_NO_MORE_SEARCH_HANDLES 

cannot allocate another search structure and handle 

114 ERRORJNVALID_TARGET_HANDLE 

target handle in DosDupHandle invalid 

115 ERROR_PROTECTION_VIOLATION 

bad user virtual address 

116 ERROR_VIOKBD_REQUEST 

error on display write or keyboard read 

117 ERRO R_i N VALi D_C ATEQORY 

category for DevlOCTL not defined 

118 ERRORJNVALID_VERIFY_SWITCH 

invalid value passed for verify flag 

119 ERROR_BAD_DRIVER_LEVEL 

Level four driver not found 

120 ERROR_CALL_NOTJMPLEMENTED 

invalid function called 

121 ERROR_SEM_TIMEOUT 

time out occurred from semaphore API function 

122 ERRORJNSUFFICIENT_BUFFER 

data buffer too small 

123 ERRORJNVALID.NAME 

illegal character or malformed file system name 

124 ERRORJNVALID_LEVEL 

unimplemented level for information retrieval or setting 

125 ERROR_NO_VOLUME_LABEL 

no volume label found with DosQFslnfo command 

126 ERROR_MOD_NOT_FOUND 

module handle not found with getprocaddr,getmodhandle 
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127 ERROR_PROC_NOT_FOUND 

procedure address not found with getprocaddr 

128 ERROR_WAIT_NO_CHILDREN 

CWait finds no cliildren 

129 ERROR_CHILD_NOT_COMPLETE 

CWajt ciiildren not terminated 

130 ERROR_DIRECT_ACCESS_HANDLE 

handle operation invalid for direct disk access handles 

131 ERROR.NEGATIVE^SEEK 

attempted seek to negative offset 
732 ERROR_SEEK_ON_DEVICE 

application tried to seek on device or pipe 

133 ERRORJS_JOIN_TARGET 

drive has previously joined drives 

134 ERRORJS_JOINED 

drive is already joined 
735 ERRORJS_SUBSTED 

drive is already substituted 

136 ERROR_NOT_JOINED 

cannot delete drive that is not joined 

137 ERROR_NOT_SUBSTED 

cannot delete drive that is not substituted 

138 ERROR_JOIN_TO_JOIN 

cannot Join to a joined drive 

739 ERROR_SUBST_TO_SUBST 

cannot substitute to a substituted drive 

740 ERROR_JOIN_TO_SUBST 

cannot join to a substituted drive 
747 ERROR_SUBST_TO_JOIN 

cannot substitute to a joined drive 

742 ERROR_BUSY_DRIVE 

specified drive is busy 

743 ERROR_SAME_DRIVE 

cannot join or substitute a drive to a directory on the same 
drive 

744 ERROR_DIR_NOT_ROOT 

directory must be a subdirectory of the root 

745 ERROR_DIR_NOT_EMPTY 

directory must be empty to use join command 

746 ERROR_IS_SUBST_PATH 

path specified is being used in a substitute 

747 ERROR_IS_JOIN_PATH 

path specified is being used in join 
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148 ERROR_PATH_BUSY 

path specified is being used by another process 

149 ERROR_IS_SUBST_TARGET 

cannot join or substitute drive having directory that Is target 
of a previous substitute 

150 ERROR_SYSTEM_TRACE 

system trace error 

151 ERROR_INVALID_EVENT_COUNT 

DosMuxSemWait errors 

152 ERROR_TOO_MANY_MUXWAITERS 

system limit of 100 entries was reached 

153 ERRORJNVALID_LIST_FORMAT 

invalid list format 

154 ERROR_LABEL_TOO_LONG 

volume label too big 

155 ERROR_TOO_MANY_TCBS 

cannot create another TCB 

156 ERROR_SIGNAL_REFUSED 

Signal refused 

157 ERROR_DISCARDED 

segment is discarded 

158 ERROR_NOT_LOCKED 

segment was not locked 

159 ERROR_BAD_THREADID_ADDR 

bad thread Id address 

160 ERROR_BAD_ARGUMENTS 

bad environment pointer 

161 ERROR_BAD_PATHNAME 

bad pathname passed to exec 

162 ERROR_SIGNAL_PENDING 

signal already pending 

163 ERROR_UNCERTAIN_MEDIA 

ERR0R_I24 mapping 

164 ERROR_MAX_THRDS_REACHED 

No more proc slots 

165 ERROR_MONITORS_NOT_SUPPORTED 

ERRORJ24 mapping 

180 ERRORJNVALID_SEGMENT_NUMBER 

invalid segment number 

181 ERROR_INVALID_CALLGATE 

Invalid call gate 

182 ERROR_INVALID_ORDINAL 

invalid ordinal 
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183 ERROR_ALREADY_EXISTS 

shared segment already exists 

184 ERROR_NO_CHILD_PROCESS 

no child process to wait for 

185 ERROR_CHILD_ALIVE_NOWAIT 

NoWalt specified & child alive 

186 ERRORJNVALID_FLAG_NUMBER 

invalid flag nunnber 

187 ERROR_SEM_NOT_FOUND 

semaphore does not exist 

188 ERROR_INVALID_STARTING_CODESEG 

invalid starting code segment, incorrect END (label)directive 

189 ERROR_INVALID_STACKSEG 

invalid stack segment 

190 ERROR_INVALID_MODULETYPE 

invalid module type - Dynamic link library file cannot be 
used as an application. Application cannot be used as a 
dynamic link library. 

191 ERRORJNVALID_EXE_SIGNATURE 

invalid EXE signature - File is DOS mode program or 
improper program. 

192 ERROR_EXE_MARKED_INVALID 

EXE marked invalid - LINK detected errors when application 
created. 

193 ERROR_BAD_EXE_FORMAT 

bad EXE format - File is DOS mode program or improper 
program. 

194 ERRORJTERATED_DATA_EXCEEDS_64k 

iterated data exceeds 64K - More than 64K of data in one of 
the segments of the file. 

195 ERRORJNVALID_MINALLOCSIZE 

invalid minimum allocation size - Size is specified to be less 
than the size of the segment data in the file. 

196 ERROR_DYNLINK_FROMJNVALID_RING 

dynamic link from invalid ring - Ring 2 routine cannot link to 
dynalink libraries. 

197 ERROR_IOPL_NOT_ENABLED 

lOPL not enabled - lOPL set to NO in CONFIG.SYS. 

198 ERROR_INVALID_SEGDPL 

Invalid segment descriptor privilege level - can only have 
privilege levels of 2 and 3 

199 ERROR_AUTODATASEG_EXCEEDS_64k 

automatic data segment exceeds 64K 
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200 ERR0R_RING2SEG_MUST_BE_M0VABLE 

ring 2 segment must be movable 

201 ERROR_RELOC_CHAIN_XEEDS_SEGLIM 

relocation chain exceeds segment limit 

202 ERROR_INFLOOP_IN_RELOC_CHAIN 

infinite loop in relocation chain segment 

203 ERROR_ENVVAR_NOT_FOUND 

environment variable not found 

204 ERROR_NOT_CURRENT_CTRY 

not current country 

205 ERROR_NO_SIGNAL_SENT 

no signal sent - No process in the command subtree has a 
signal handler. 

206 ERROR_FILENAME_EXCED_RANGE 

filename/extension greater than 8.3 

207 ERR0R_RING2_STACKJN_USE 

ring 2 stack in use 

208 ERROR_META_EXPANSION_TOO_LONG 

meta expansion is too long 

209 ERROR_INVALID_SIGNAL_NUMBER 

invalid signal number 

210 ERR0R_THREAD_1_INACTIVE 

inactive thread 

211 ERRORJNFO_NOT_AVAILABLE 

filesystem information not available for this file 

212 ERROR_LOCKED 

locked error 

213 ERROR_BAD_DYNALINK 

attempted to execute non family API in DOS mode 

214 ERROR_TOO_MANY_MODULES 

too many modules 

215 ERROR_NESTING_NOT_ALLOWED 

nesting not allowed 

303 ERROR_INVALID_PROCID 

invalid process ID 

304 ERRORJNVALID_PDELTA 

invalid priority delta 

305 ERROR_NOT_DESCENDANT 

not descendant 

306 ERROR_NOT_SESSION_MANAGER 

requestor not session manager 

307 ERRORJNVALiD_PCLASS 

invalid P class 



308 ERROR_INVALID_SCOPE 

invalid scope 

309 ERROR_INVALID_THREADID 

invalid thread id 

310 ERROR_DOSSUB_SHRINK 

cannot shrink segment - DosSubSet 

311 ERROR_DOSSUB_NOMEM 

no memory to satisfy request - DosSubAlloc 

312 ERROR_DOSSUB_OVERLAP 

overlap of specified block with an allocated memory - 
DosSubFree 

313 ERROR_DOSSUB_:BADSIZE 

bad size parameter - DosSubAlloc or DosSubFree 

314 ERROR_DOSSUB_BADFLAG 

bad flag parameter - DosSubSet 

315 ERROR_DOSSUB_BADSELECTOR 

invalid segment selector 
376 ERROR_MR_MSG_TOO_LONG 
message too long for buffer 

317 ERROR_MR_MID_NOT_FOUND 

message ID number not found 

318 ERROR_MR_UN_ACC_MSGF 

unable to access message file 

319 ERROR_MRJNV_MSFG_FORMAT 

invalid message file format 

320 ERROR_MRJNV_IVCOUNT 

invalid insertion variable count 

321 ERROR_MR_UN_PERFORM 

unable to perform function 

322 ERROR_TS_WAKEUP 

unable to wake up 

323 ERROR_TS_SEMHANDLE 

invalid system semaphore 

324 ERROR_TS_NOTIMER 

no timers available 

326 ERROR_TS_HANDLE 

invalid timer handle 

327 ERROR_TS_DATETIME 

date or time invalid 

328 ERROR_SYS_INTERNAL 

internal system error 

329 ERROR_QUE_CURRENT_NAME 

current queue name does not exist 



330 ERROR_QUE_PROC_NOT_OWNED 

current process does not own queue 

331 ERROR_QUE_PROC_OWNED 

current process owns queue 

332 ERROR_QUE_DUPLICATE 

duplicate queue name 

333 ERROR_QUE_ELEMENT_NOT_EXIST 

queue element does not exist 

334 ERROR_QUE_NO_MEMORY 

inadequate queue memory 

335 ERROR_QUE_INVALID_NAME 

invalid queue name 

336 ERROR_QUEJNVALID_PRIORITY 

invalid queue priority parameter 

337 ERROR_QUE_INVALID_HANDLE 

invalid queue handle 

338 ERROR_QUE_LINK_NOT_FOUND 

queue link not found 

339 ERROR_QUE_MEMORY_ERROR 

queue memory error 

340 ERROR_QUE_PREV_AT_END 

previous queue element was at end of queue 

341 ERROR_QUE_PROC_NO_ACCESS 

process does not have access to queues 

342 ERROR_QUE_EMPTY 

queue is empty 

343 ERROR_QUE_NAME_NOT_EXIST 

queue name does not exist 

344 ERROR_QUE_NOTJNmALIZED 

queues not initialized 

345 ERROR_QUE_UNABLE_TO_ACCESS 

unable to access queues 

346 ERROR_QUE_UNABLE_TO_ADD 

unable to add new queue 

347 ERROR_QUE_UNABLE_TOJNIT 

unable to initialize queues 

349 ERROR_VIOJNVAUD_MASK 

invalid function replaced 

350 ERROR_VIO_PTR 

invalid pointer to parameter 
355 ERROR_VIO_MODE 

unsupported screen mode 
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356 ERROR_VIO_WIDTH 

invalid cursor width value 

358 ERROR_VIO_ROW 

invalid row value 

359 ERROR_VIO_COL 

invalid column value 

366 ERROR_VIO_WAIT_FLAG 

invalid wait flag setting 

367 ERROR_VIO_UNLOCK 

screen not previously locked 

369 ERROR_SMGJNVALID_SESSIONJD 

invalid session ID 

370 ERROR_SMG_NO_SESSIONS 

no sessions available 

371 ERROR_SMG_SESSION_NOT_FOUND 

session not found 

372 ERROR_SMG_SET_TITLE 

title sent by shell or parent cannot be changed 

373 ERROR_KBD_PARAMETER 

invalid parameter to Kbd 

375 ERROR_KBDJNVALIDJOWAIT 

invalid I/O wait specified 

376 ERROR_KBDJNVALID_LENGTH 

invalid length for keyboard 

377 ERROR_KBDJNVALID_ECHO_MASK 

invalid echo mode mask 

378 ERROR_KBDJNVALIDJNPUT_MASK 

invalid input mode mask 

379 ERROR_MON_INVALID_PARMS 

invalid parameters to DosMon 

380 ERROR_MONJNVALID_DEVNAME 

invalid device name string 

381 ERROR_MONJNVALID_HANDLE 

invalid device handle 

382 ERROR_MON_BUFFER_TOO_SMALL 

buffer too small 

383 ERROR_MON_BUFFER_EMPTY 

buffer is empty 

384 ERROR_MON_DATA_TOO_LARGE 

data record too large 
?86 ERROR_MOUSE_INV_HANDLE 

Mouse device closed (invalid device handle) 



389 ERROR_MOUSE_DISPLAY_PARMS 

parameters invalid for display mode 

391 ERROR_MOUSEJNV_ENTRY_PT 

entry point not valid 

392 ERROR_MOUSEJNV_MASK 

function mask Invalid 

394 NO_ERROR_MOUSE_P TR_DRAWN 

pointer drawn 

395 ERRORJNVALID_FREQUENCY 

Invalid frequency for beep 

396 ERROR_NLS_NO_COUNTRY_FILE 

can't find country.sys file 

397 ERROR_NLS_OPEN_FAILED 

can't open country.sys file 

398 ERROR_NO_COUNTRY_OR_CODEPAGE 

country code not found 

399 ERROR_NLS_TABLE_TRUNCATED 

table returned information truncated, buffer too small 

400 ERROR_NLS_BAD_TYPE 

selected type does not exist 

401 ERROR_NLS_TYPE_NOT_FOUND 

selected type not in file 

402 ERROR_VIO_SMG_ONLY 

valid from session manager only 

403 ERROR_VIO_INVALID_ASCIIZ 

Invalid ASCIIZ length 

404 ERROR_VIO_DEREGISTER 

VioDeRegister not allowed 

405 ERROR_VIO_NO_POPUP 

popup not allocated 

406 ERROR_VIO_EXISTING_POPUP 

popup on screen (no wait) 

407 ERROR_KBD_SMG_ONLY 

valid from session manager only 

408 ERROR_KBD_INVALID_ASCIIZ 

invalid ASCIIZ length 

409 ERROR_KBDJNVALID_MASK 

invalid replacement mask 

410 ERROR_KBD_REGISTER 

KbdRegister not allowed 

411 ERROR_KBD_DEREGISTER 

KbdDeRegister not allowed 
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412 ERROR_MOUSE_SMG_ONLY 

valid from session manager only 

413 ERROR_MOUSEJNVAUD_ASCIIZ 

invalid ASCIIZ length 

414 ERROR_MOUSEJNVALID_MASK 

invalid replacement mask 

415 ERROR_MOUSE_REGISTER 

Mouse register not allowed 

416 ERROR_MOUSE_DEREGISTER 

Mouse dereglster not allowed 

417 ERROR_SMG_BAD_ACTION 

Invalid action specified 

418 ERROR_SMG_INVALID_CALL 

INIT called more than once 

419 ERROR_SCS_SG_NOT_FOUND 

new screen group number 

420 ERROR_SCS_NOT_SHELL 

caller Is not shell 

421 ERROR_VIOJNVALID_PARMS 

invalid parms passed 

422 ERROR^VIO^FUNCTION.OWNED 

save/restore already owned 

423 ERROR_VIO_RETURN 

non-destruct return (undo) 

425 ERROR_SCS_NOT_SESSION_MGR 

caller not session manager 

426 ERROR_VIO_REGISTER 

Vio register not allowed 

427 ERROR_VIO_NO_MODE_THREAD 

no mode restore thread in SG 

428 ERROR_VIO_NO_SAVE_RESTORE_THD 

no save/ rest thread In SG 

429 ERROR_VIO_IN_BG 

function invalid in background 

430 ERROR_VIOJLLEGAL_DURING_POPUP 

function not allowed during popup 

431 ERROR_SMG_NOT_BASESHELL 

caller Is not the base shell 

432 ERROR_SMG_BAD_STATUSREQ 

invalid status requested 

433 ERROR_QUEJNVALID_WAIT 

nowait parameter out of bounds 



434 ERROR_VIO_LOCK 

error returned from scrlock 

435 ERROR_MOUSEJNVALID_IOWAIT 

invalid parameters for lOWait 

436 ERROR_VIOJNVALID_HANDLE 

invalid vio handle 

438 ERROR_VIO_INVALID_LENGTH 

invalid vio length 

439 ERROR_KBDJNVALID_HANDLE 

invalid kbd handle 

440 ERROR_KBD_NO_MORE_HANDLE 

ran out of handles 

441 ERROR_KBD_CANNOT_CREATE_KCB 

unable to create kcb 

442 ERROR_KBD_CODEPAGE_LOADJNCOMPL 

unsuccessful codepage load 

443 ERROR_KBDJNVALID_CODEPAGE_ID 

Invalid codepage id 

444 ERROR_KBD_NO_CODEPAGE_SUPPORT 

no codepage support 

445 ERROR_KBD_FOCUS_REQUIRED 

keyboard focus required 

446 ERROR_KBD_FOCUS_ALREADY_ACTIVE 

calling thread has an outstanding focus 

447 ERROR_KBD_KEYBOARD_BUSY 

keyboard busy 

448 ERROR_KBDJNVALID_GODEPAGE 

invalid codepage 

449 ERROR_KBD_UNABLE_TO_FOCUS 

focus attempt failed 

450 ERROR_SMG_SESSION_NON_SELECT 

session is not selectable 

451 ERROR_SMG_SESSION_NOT_FOREGRND 

parent/child session not foreground 

452 ERROR_SMG_SESSION_NOT_PARENT 

not parent of requested child 

453 ERROR_SMGJNVALID_START_MODE 

invalid session start mode 

454 ERROR_SMGJNVALID_RELATED_OPT 

invalid session start related option 

455 ERROR_SMGJNVALID_BOND_OPTION 

invalid session bond option 
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456 ERROR_SMGJNVALID_SELECT_OPT 

invalid session select option 

457 ERROR_SMG_STARTJN_BACKGROUND 

session started In background 

458 ERROR_SMGJNVALID_STOP_OPTION 

invalid session stop option 

459 ERROR_SMG_BAD_RESERVE 

reserved parameters not zero 

460 ERROR_SMG_PROCESS_NOT_PARENT 

session parent process already exists 

461 ERROR_SMG_INVALID_DATA_LENGTH 

invalid data length 

462 ERROR_SMG_NOT_BOUND 

parent not bound 

463 ERROR_SMG_RETRY_SUB_ALLOC 

retry request block allocation 

464 ERROR_KBD_DETACHED 

this call disallowed for detached pid 

465 ERROR_VIO_DETACHED 

this call disallowed for detached pid 

466 ERROR_MOU_DETACHED 

this call disallowed for detached pid 

467 ERROR_VIO_FONT 

no font available to support mode 

468 ERROR_VIO_USER_FONT 

user font active 

469 ERROR_VIO_BAD_CP 

invalid code page specified 

470 ERROR_VIO_NO_CP 

system displays don't support code page 

471 ERROR_VIO_NA_CP 

current display does not support code page 

472 ERROR_INVALID_CODE_PAGE 

invalid code page 

473 ERROR_CPLIST_TOO_SMALL 

code page list is too small 

474 ERROR_CP_NOT_MOVED 

code page not moved 

475 ERROR_MODE_SWITCHJNIT 

mode switch init error 

476 ERROR_CODE_PAGE_NOT_FOUND 

code page not found 



477 ERROR_UNEXPECTED_SLOT_RETURNED 

Internal error 

478 ERROR_SMG_INVALID_TRACE_OPTION 

invalid start session trace indicator 

479 ERROR_VIO_INTERNAL_RESOURCE 

vio Internal resource error 

480 ERROR_VIO_SHELL_INIT 

vio shell init error 
487 ERROR_SMG_NO_HARD_ERRORS 
no session manager hard errors 

482 ERROR_CP_SWITCHJNCOMPLETE 

DosSetCp unable to set kbd/vio cp 

483 ERROR_VIO_TRANSPARENT_POPUP 

error during vio popup 

484 ERROR_CRITSEC_OVERFLOW 

critical section overflow 

485 ERROR_CRITSEC_UNDERFLOW 

critical section underflow 

486 ERROR_VIO_BAD_RESERVE 

reserved parameter is not zero 

487 ERRORJNVALID_ADDRESS 

bad physical address 

488 ERROR_ZERO_SELECTORS_REQUESTED 

at least one selector must be requested 

489 ERROR_NOT_ENOUGH_SELECTORS_AVA 

not enough GDT selectors to satisfy request 

490 ERRORJNVALID.SELECTOR 

not a GDT selector 
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COM/RI/return 6-54 

COI^/RLSD - DCD 6-6 

COM/status/return 6-49 

COM/transmit data 
status/return 6-51 
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COM/transmit queue/return 
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COM/Tx break status/return 6-47 

COM/XOFF/simulate 6-18 
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country information 2-74 

Critical Section 
enter 2-39 
exit 2-53 
of execution 2-39 
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date, get 2-77 
date, set 2-224 
DBCS vector 2-79 
Device 

configuration 2-32 

I/O control 2-34 

installed 2-32 
device buffer control lOCtIs 6-191 
Device Monitor 

close connection 2-118 

open connection 2-119 

read input 2-121 

register buffers 2-124 

write output 2-127 
Directory 

change current 2-13 
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Disk 

partitionable support 2-161 
query current 2-177 
select drive 2-208 
disk control lOCtI, get device 

parameters 6-177 
disk control lOCtI, get physical 

device parameters 6-185 
disk control lOCtIs 6-179 
disk, (logical) control lOCtts 6-162 
disk, (physical) control 

lOCtIs 6-179 
diskette control lOCtI, get device 

parameters 6-177, 6-185 
DosAllocHuge 2-2 
DosAliocSeg 2-5 
DosAllocShrSeg 2-7 
DosBeep 2-9 
DosBuf Reset 2-10 
DosCaseMap 2-11 
DosChDir 2-13 
DosChgFlleRr 2-14 
DosCLI Access 2-16 
DosClose 2-17 
DosCloseQueue 2-18 
DosCioseSem 2-19 
DosCreateCSAIias 2-20 
DosCreateQueue 2-22 
DosCreateSem 2-24 
DosCreateThread 2-26 
DosCwait 2-28 
DosDelete 2-31 
DosDevConfig 2-32 
DosDevlOCtI 2-34 
DosDupHandle 2-37 
DosEnterCritSec 2-39 
DosErrClass 2-41 
DosError 2-44 
DosExecPgm 2-46 
DosExit 2-51 
DosExltCritSec 2-53 
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DosFlleLocks 2-56 
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DosFindClose 2-58 
DosFindFirst 2-59 
DosFindNext 2-63 
DosFlagProcess 2-65 
DosFreeModule 2-67 
DosFreeSeg 2-68 
DosGetCollate 2-70 
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DosGetDateTime 2-77 
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DoslnsMessage 2-106 
DosKillProcess 2-108 
DosLoadModule 2-110 
DosLockSeg 2-112 
OosMakePipe 2-114 
DosMemAvail 2-116 
DosMkDir 2-117 
DosMonClose 2-118 
DosMonOpen 2-119 
DosMonRead 2-121 
DosMonReg 2-124 
DosMonWrite 2-127 
DosMove 2-130 
DosMuxSemWalt 2-132 
DosNewSize 2-134 
DosOpenQueue 2-143 
DosOpenSem 2-144 
DosPeekQueue 2-146 



DosPFSActivate 2-149 
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DosPFSQueryAct 2-157 
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DosPortAccess 2-164 
DosPtrace 2-166 
DosPurgeQueue 2-174 
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DosQFHandState 2-178 
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DosSleep 2-251 
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load module 2-110 
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change size 2-134 

delete 2-31 
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query mode 2-183 
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set maximum 2-234 
set state 2-225 
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query active 2-157 

verify 2-159 
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general device control 

lOCtIs 6-191 
generic lOCtls/COM 6-6 
Get Device Parameters 6-177 
Get Version Number 2-101 

H 

Handle 

query type 2-187 
hard error processing 2-44 

I 

I/O Privilege 

disable/enable interrupts 2-16 

port access 2-164 
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request/release access 2-164 
lOCtI 
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mands 6-188 
command summary 6-2 
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l<eyboard control 

commands 6-71 
logical disk control 6-162 
mouse control commands 6-129 
physical disk control 
commands 6-179 
printer control commands 6-115 
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Control 6-69 
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Control 6-71 
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control 6-129 
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set priority 3-26 
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Keyboard (continued) 

synchronize access 3-33 
translate scan code 3-34 

Keyboard Control 6-71 

L 

level triggered 2-214 
logical disk control lOCtI 
commands 6-162 
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matching file, find first 2-59 
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return code classification 2-41 
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disable/enable 2-104 
send control break 2-221 
send control C 2-221 

speaker sound 2-9 

Subdirectory 
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